doc/dynamicbox_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 #ifndef __DYNAMICBOX_DOC_H__
  19 #define __DYNAMICBOX_DOC_H__
  20
  21 /**
  22  * @defgroup DYNAMICBOX_UTILITY_MODULE dynamicbox
  23  * @brief Supports APIs for development of inhouse dynamic box
  24  * @ingroup CAPI_DYNAMICBOX_FRAMEWORK
  25  * @section DYNAMICBOX_UTILITY_MODULE_HEADER Required Header
  26  *   \#include <dynamicbox.h>
  27  * @section DYNAMICBOX_UTILITY_MODULE_OVERVIEW Overview
  28 <H1>Dynamic Box Utility functions</H1>
  29
  30 <H2>1. Script type Dynamic Box</H2>
  31 If you choose the Script Type DBox, you have to use this.
  32
  33 Dynamic Box defines its own syntax to share the content between home application and provider application.
  34 It is called "Description Data Syntax"
  35
  36 To generate it you have to use following functions.
  37
  38 @code
  39 struct dynamicbox_desc *desc_handle;
  40 int idx;
  41
  42 desc_handle = dynamicbox_desc_open(id, 0);
  43 if (!desc_handle) {
  44     // Error
  45 }
  46
  47 dynamicbox_desc_set_size(desc_handle, id, 720, 360);
  48
  49 // Loads sub-layout object into main layout
  50 idx = dynamicbox_desc_add_block(desc_handle, NULL, DBOX_DESC_TYPE_SCRIPT, "sub,layout", "/usr/apps/com.samsung.my-app/shared/res/dbox.edj", "sub,group");
  51 dynamicbox_desc_set_id(desc_handle, idx, "sub,layout");
  52
  53 // Set a text for sub-layout object
  54 dynamicbox_desc_add_block(desc_handle, "sub,layout", DBOX_DESC_TYPE_TEXT, "sub,layout,text", "Hello World", NULL);
  55
  56 // Flushes changes, the content will be changed after close this handle.
  57 dynamicbox_desc_close(desc_handle);
  58 desc_handle = NULL;
  59 @endcode
  60
  61 Only after you close the desc_handle, the provider will send changes to the dynamic box manager service.
  62 And if it needs to propagate events to the home application, the home application will get changes event.
  63
  64 <H2>2. Window(buffer) type Dynamic Box</H2>
  65
  66 @code
  67 Evas_Object *parent;
  68 Evas_Object *win;
  69
  70 parent = dynamicbox_get_evas_object(id, 0);
  71 if (!parent) {
  72     // Error
  73 }
  74
  75 win = elm_win_add(parent, "Dynamic Box Window", ELM_WIN_DYNAMIC_BOX);
  76 evas_object_del(parent);
  77 if (!win) {
  78     // Error
  79 }
  80 @endcode
  81
  82 To create a window for dynamic box,
  83 You have to get the parent object using dynamicbox_get_evas_object().
  84 And after creating a window for dynamic box, you have to delete it.
  85 Its attributes will be passed to the newly created window. So you don't need keep the parent object anymore.
  86
  87 After creating a window, you can do what you want like an application.
  88 Creatig any core-control such as button, list, etc, ....
  89
  90 <H2>3. Image type Dynamic Box</H2>
  91 This kind of dynamic box should create an image file using given Id.
  92 The Id's syntax is "file://ABS_PATH_OF_OUTPUT_FILE", so you should create an image file using this URI.
  93 The Id will be assigned to every dynamic box instances.
  94 And those are unique.
  95
  96 If you create an image file, you should notify it to the viewer using dynamicbox_provider_app_dbox_updated()
  97 it is provided by libdynamicbox_provider_app package.
  98
  99 <H2>4. Text type Dynamic Box (Experimental)</H2>
 100 In case of text type, you may have no window or script file.
 101 The text type dynamic box only needs to generate content data using dynamicbox_desc_XXXX series APIs.
 102 Of course, after you prepare the desc file, you have to call dynamicbox_provider_app_dbox_updated() function too.
 103 Then the viewer will get your updated contents and try to parse it to locate content of dynamic box to its screen.
 104 But, unfortunately, this type of dynamic box is not fully supported yet.
 105 Because it very highly depends on the viewer implementations.
 106 So if the viewer doesn't support this type of dynamic box, you cannot do anything for user.
 107
 108 To generate the text data, you can use below API set.
 109
 110  - dynamicbox_desc_open()
 111  - dynamicbox_desc_set_category()
 112  - dynamicbox_desc_set_size()
 113  - dynamicbox_desc_set_id()
 114  - dynamicbox_desc_add_block()
 115  - dynamicbox_desc_del_block()
 116  - dynamicbox_desc_close()
 117
 118 Here is a sample code for you.
 119 \code
 120 #define FOR_GBAR 1
 121 #define FOR_DBOX 0
 122
 123 struct dynamicbox_desc *handle;
 124 int idx;
 125
 126 handle = dynamicbox_desc_open(handle, FOR_GBAR); // The second parameter will help you choose to target, for glance bar or dynamic box?
 127 idx = dynamicbox_desc_add_block(handle, NULL, DBOX_DESC_TYPE_SCRIPT, "/opt/usr/apps/your.company.application/shared/resource/edje/script.edj", "sample", NULL);
 128 dynamicbox_desc_set_id(handle, idx, "sample");
 129 dynamicbox_desc_close(handle);
 130 dynamicbox_provider_app_dbox_updated(dbox_id, 0, 0);
 131 \endocde
 132
 133  */
 134
 135 #endif /* __DYNAMICBOX_DOC_H__ */