doc/shortcut_doc.h

   1 /*
   2  * Copyright (c) 2000 - 2013 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 #ifndef __SHORTCUT_DOC_H__
  19 #define __SHORTCUT_DOC_H__
  20
  21 /**
  22  * @defgroup SHORTCUT_MODULE Shortcut
  23  * @brief To enhance the Add to home feature. Two types of API set are supported.
  24  *   - One for the homescreen developers.
  25  *   - The others for the application developers who should implement the Add to home feature.
  26  * @ingroup CAPI_APPLICATION_FRAMEWORK
  27  * @section SHORTCUT_MODULE_HEADER Required Header
  28  *   \#include <shortcut.h>
  29  * @section SHORTCUT_MODULE_OVERVIEW Overview
  30 <H1>1. Shortcut</H1>
  31 Tizen is supporting the "add shortcut or add to home" for various applications.
  32 Developers may use the shortcut library (libshortcut) to implement features sending (applications) and receiving (possibly home screen) shortcuts.
  33 If home screen implements the shortcut service using the library, the applications are good to go for adding their shortcuts to the home screen(, and vice versa.)
  34
  35 <H1>2. How to add a new shortcut to the home screen</H1>
  36 <H2>2.1 Add to home (From the app to home)</H2>
  37
  38 The followings are two separate APIs to support  "add to home" feature.
  39
  40 \code
  41 typedef int (*result_cb_t)(int ret, int pid, void *data)
  42
  43 extern int add_to_home_shortcut(const char *pkgname, const char *name, int type, const char *content_info, const char *icon, result_cb_t result_cb, void *data)
  44
  45 extern int add_to_home_dynamicbox(const char *pkgname, const char *name, int type, const char *content, const char *icon, double period, result_cb_t result_cb, void *data)
  46 \endcode
  47
  48 Currently, our home screen can contain two different types of contents (that are pure shortcuts and dynamicboxes).
  49
  50 To add a pure shortcut i.e., simply for launching an app, developers can use "add_to_home_shortcut" API to deliver their shortcuts to a home screen.
  51
  52 If your application supports our dynamicbox service and implments dynamicbox type shortcut, then you can use "add_to_home_dynamicbox" API to have a home screen add the dynamicbox on its screen.
  53
  54 <TABLE>
  55 <TR><TH>Parameters</TH><TH>Comment</TH></TR>
  56 <TR><TD>pkgname</TD><TD>Package name</TD></TR>
  57 <TR><TD>name</TD><TD>Application name wich will be displayed on the screen</TD></TR>
  58 <TR><TD>type</TD><TD>Basically it describes launching options whether to use a package name or URI. LAUNCH_BY_PACKAGE or LAUNCH_BY_URI</TD></TR>
  59 <TR><TD>content</TD><TD>
  60 Application data used for creating a pure shortcut or creating a dynamicbox
  61
  62     Shortcut
  63
  64 1. if the type is Launch by package: None
  65
  66 2. if the type is Launch by URI: put the URI in the content
  67
  68     Dynamicbox: any data necessary to create a dynamicbox. Basically, it will passed to the dynamicbox plug-in's create function.
  69 </TD></TR>
  70 <TR><TD>icon</TD><TD>Absolute path to the icon file, If you set this "NULL", the home screen will use the deafult icon file (but it is depends on the homescreen implementations)</TD></TR>
  71 <TR><TD>period</TD><TD>&lt;Only for dynamicbox> Update period. The period must be greater than 0.0f</TD></TR>
  72 <TR><TD>result_cb</TD><TD>Result callback. The callback will be called after a shortcut or dynamicbox has been added. Don't forget to check the return value.</TD></TR>
  73 <TR><TD>data</TD><TD>Callback data</TD></TR>
  74 </TABLE>
  75
  76 <H3>2.1.1 Supported types</H3>
  77 \snippet lib/include/shortcut.h Enumeration values for type of shortcuts
  78
  79 <H2>2.2 Add shortcut (Home screen retrieves shortcuts from app)</H2>
  80 "Add shortcut " service enables home screen to retrieve all shortcuts that applications promised to support and request an app to send their shortcuts to home directly, as opposed to "add to home".
  81
  82 It is initiated by home screen as opposed to "add to home" which is initiated by an application."Add shortcut " service enables home screen to retrieve all shortcuts that applications promised to support and request an app to send their shortcuts to home directly, as opposed to "add to home".
  83
  84 It is initiated by home screen as opposed to "add to home" which is initiated by an application.
  85
  86 <H3>2.2.1 Build the shortcut list DB</H3>
  87 \image html BuildShortcutList.png
  88
  89 To recognize how many and what kinds of shortcuts have been registerred, each application who wants to support "add shortcut" service needs to install the XML file that defines "shortcut" information.
  90 The following table describes the format and information necessary to define the shortcuts application can support.
  91 Then, the information will be shown and used in home screen when a user selects "add shortcut" service.
  92
  93 <TABLE>
  94 <TH><TD>Syntax of the shortcut manifest file</TD></TH>
  95 <TR><TD>
  96 \code
  97 <manifest xmlns="http://tizen.org/ns/packages" package="com.samsung.APP_PKGNAME">
  98 ...
  99     <shortcut-list>
 100         <shortcut appid="com.samsung.myapp" extra_key="key_string" extra_data="data_string_for_key">
 101            <icon>/opt/share/icons/default/small/com.samsung.myapp-shortcut.png</icon>
 102            <label>Default name</label>
 103            <label xml:lang="en-us">Name en</label>
 104            <label xml:lang="nl-nl">Name nl</label>
 105            <label xml:lang="de-de">Name de</label>
 106            <label xml:lang="zh-hk">Name hk</label>
 107            <label xml:lang="zh-cn">Name cn</label>
 108            <label xml:lang="ru-ru">Name ru</label>
 109            <label xml:lang="zh-tw">Name tw</label>
 110            <label xml:lang="ja-jp">Name jp</label>
 111            <label xml:lang="es-es">Name es</label>
 112            <label xml:lang="el-gr">Name gr</label>
 113            <label xml:lang="it-it">Name it</label>
 114            <label xml:lang="tr-tr">Name tr</label>
 115            <label xml:lang="pt-pt">Name pt</label>
 116            <label xml:lang="fr-fr">Name fr</label>
 117            <label xml:lang="ko-kr">Name kr</label>
 118         </shortcut>
 119         <shortcut appid="com.samsung.myapp" extra_key="key_string" extra_data="data_string_for_key">
 120            <label>Default name</label>
 121         </shortcut>
 122         ...
 123         <shortcut appid="com.samsung.myapp" extra_key="key_string" extra_data="data_string_for_key">
 124            <label>Default name</label>
 125            <icon>/opt/share/icons/default/small/com.samsung.myapp2.png</icon>
 126         </shortcut>
 127     </shortcut-list>
 128 ...
 129 </manifest>
 130 \endcode
 131 </TD></TR>
 132 </TABLE>
 133
 134 Install this XML file to /opt/share/packages/YOUR_PKGNAME.xml (Note: After manifest has been applied to the binary, simply copy the content to your manifest file.)
 135 Shortcut listing application will list up these items on its screen and each item will be displayed using the string in label field.
 136 When selected, it will launch the selected app using app service with "appid" and a bundle holding data in the pair of extra_key and extra-data fields.
 137 Obviously, icon will be used to display visual information for given shortcut type.(that said the icon could be other than the application's default icon)
 138
 139 <H3>2.2.2 Jump to the APP</H3>
 140 \image html JumpToApp.png
 141
 142 Shortcut listing application will launch your application using app-svc with package name and param attributes.
 143 It will use the pkgname and param attrbute to launch your application.
 144 Shortcut list view will launch your "[App] Shortcut list" using followed code.
 145
 146 <TABLE>
 147 <TH><TD>Launch your app from shortcut list viewer</TD></TH>
 148 <TR><TD>
 149 \code
 150 service_h service;
 151 service_create(&service);
 152 service_set_package(service, APPID); /* <shortcut appid="APPID" ...> */
 153 service_add_extra_data(service, EXTRA_KEY, EXTRA_DATA); /* <shortcut extra_key="EXTRA_KEY" extra_data="EXTRA_DATA" ...> */
 154 ret = service_send_launch_request(service, NULL, NULL);
 155 if (ret ...) { }
 156 service_destroy(service);
 157 \endcode
 158 </TD></TR>
 159 </TABLE>
 160 When your app is launched, the app should send a selected item as a shortcut or dynamicbox to the home screen using "add_to_home" series functions mentioned above.
 161
 162 <H3>2.2.3 What each app has to do</H3>
 163 You can implement your shortcut list view using App or UG.
 164
 165 Who is going to handle the shortcut
 166
 167 <UL>
 168 <LI>Handled by App
 169         <LI>App should prepare a shortcut-add view as guided</LI>
 170 </LI>
 171 <LI>Handeld by UG
 172         <LI>UG should be launched as an app and provide the shortcut-add view</LI>
 173 </LI>
 174 </UL>
 175
 176 In your shortcut list view, you just call the "add_to_home_shortcut" or "add_to_home_dynamicbox" which are described in the section 2.1
 177
 178 <H4>2.2.3.1 Handled by App</H4>
 179 \image html ShortcutApp.png
 180 When your application is launched by the shortcut list application (displayed on the left most of above figure).
 181 Your application should go back to the normal view when you receive the PAUSE event.
 182 If you didn't change the view of your application, the user will see this shortcut list view again even if the user
 183 launches your application from the app-tray(or homescreen).
 184 So you have to change the view from the shortcut list to the normal(or previous) view when you get the PAUSE event.
 185
 186 <H4>2.2.3.2 Handled by UG</H4>
 187 \image html ShortcutUG.png
 188 In this case, the Shortcut List application will launch your UG as a process.
 189 When you receive PAUSE event, or need to change to other view (not in the same UG), you should destroy current UG.
 190 If you didn't destroy it, it will be reside on the process list. and it will not be destroyed automatically.
 191
 192 Currently, UG container process only supporting the multiple instance for a process.
 193 So if the user tries to add a new shortcut again from the shortcut list application, your UG will be launched again if you didn't
 194 terminate previous UG process (when you got PAUSE event).
 195
 196 <H1>3. What the home screen should do</H1>
 197 \code
 198 typedef int (*request_cb_t)(const char *pkgname, const char *name, int type, const char *content_info, const char *icon, int pid, double period, void *data)
 199 extern int shortcut_set_request_cb(request_cb_t request_cb, void *data)
 200 \endcode
 201
 202 <TABLE>
 203 <TR><TH>Parameter</TH><TH>Comment</TH></TR>
 204 <TR><TD>pkgname</TD><TD>Package name to be added</TD></TR>
 205 <TR><TD>name</TD><TD>Application name to be displayed on the screen</TD></TR>
 206 <TR><TD>type</TD><TD>LAUNCH_BY_PACKAGE or LAUNCH_BY_URI</TD></TR>
 207 <TR><TD>content_info</TD><TD>Used for the dynamicbox, or homescreen by itself if it required.</TD></TR>
 208 <TR><TD>icon</TD><TD>Absolute path of the icon file. (If it is not exists, the homescreen can use the deafult icon file)</TD></TR>
 209 <TR><TD>pid</TD><TD>Reuquestor's Process ID</TD></TR>
 210 <TR><TD>period</TD><TD>Update period only for the dynamicbox</TD></TR>
 211 <TR><TD>data</TD><TD>Callback data</TD></TR>
 212 </TABLE>
 213
 214 <H1>4. To list up shortcuts registred in the device</H1>
 215 <TABLE>
 216 <TR><TH>shortcut-list viewer will launch your app by this way</TH></TR>
 217 <TR><TD>
 218 \code
 219 int shortcut_get_list(const char *pkgname, int (*cb)(const char *pkgname, const char *icon, const char *name, const char *extra_key, const char *extra_data, void *data), void *data)
 220 \endcode
 221 </TD></TR>
 222 </TABLE>
 223
 224 If you specified the "pkgname", this API will only gathering the given Package's shortcut list.
 225 If you set is to NULL, this API will gathering all shortcuts.
 226 Every shortcut item will be passed via "cb" callback function. so it will be invoked N times if the number of registered shortcut item is N.
 227 pkgname and name and param is described in the XML file of each application package.
 228 It will returns the number of shortcut items, or return <0 as an error value.
 229
 230 -EIO : failed to access shortcut list DB
 231 > 0 : Number of shortcut items (count of callback function calling)
 232  *
 233  */
 234
 235 #endif /* __SHORTCUT_DOC_H__ */