--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+ <meta http-equiv="X-UA-Compatible" content="IE=9" />
+ <link rel="stylesheet" type="text/css" href="../css/styles.css" />
+ <link rel="stylesheet" type="text/css" href="../css/snippet.css" />
+ <script type="text/javascript" src="../scripts/snippet.js"></script>
+ <script type="text/javascript" src="../scripts/jquery.util.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../scripts/common.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../scripts/core.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../scripts/search.js" charset="utf-8"></script>
+
+ <title>Attach Panel</title>
+</head>
+
+<body class="no-toc" onload="prettyPrint()" style="overflow: auto;">
+
+<div id="toc-navigation">
+</div>
+
+<div id="container"><div id="contents"><div class="content">
+ <div id="profile">
+ <p><img alt="Mobile native" src="../images/mobile_s_n.png"/></p>
+ </div>
+
+ <h1>Attach Panel Sample Overview</h1>
+<p>The Attach Panel sample application demonstrates how to use Attach Panel API to quickly create attachments. The API
+allows you to add files stored on the device to your application as well as to create new attachments on the spot.</p>
+
+<table>
+<col/>
+<tr>
+ <td>
+ <p class="figure">Figure 1: Attach Panel sample app main view</p>
+ <p align="center"><img alt="Attach Panel sample app main view" src="../images/attach_panel_main_view.png" /></p>
+ </td>
+ <td>
+ <p class="figure">Figure 2: Attach Panel sample app view with the attach panel visible</p>
+ <p align="center"><img alt="Attach Panel sample app view with the attach panel visible" src="../images/attach_panel_main_view_with_items.png" /></p>
+ </td>
+ <td>
+ <p class="figure">Figure 3: Attach Panel sample app view with filled attachment's gengrid</p>
+ <p align="center"><img alt="Attach Panel sample app view with filled attachment's gengrid" src="../images/attach_panel_main_view_full.png" /></p>
+ </td>
+</tr>
+</table>
+
+<p>The Attach Panel API provides functions that allow you to quickly attach various types of files to your application and create new attachments
+ without having to explicitly launch other apps. The Attach Panel module takes care of creating its UI and getting the data from the device. All you need to do is to create
+ an attach panel and specify which types of attachments you want to be able to generate.</p>
+
+<p>The types of attachments you can add to your application using Attach Panel are defined by the content categories. You can choose one or more of the following categories:</p>
+ <ul>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_IMAGE</span> - attach images from Gallery;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_CAMERA</span> - take a picture to be attached;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_VOICE</span> - record an audio file to be attached;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_VIDEO</span> - attach video files from Gallery;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_AUDIO</span> - attach audio files from My Files;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_CALENDAR</span> - attach calendar data from Calendar;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_CONTACT</span> - attach contact data from Contacts;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_MYFILES</span> - attach files from My Files;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_VIDEO_RECORDER</span> - record a video file to be attached.</li>
+</ul>
+
+<p>This sample application uses <span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_IMAGE</span> (Fig. 4),
+<span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_CAMERA</span> (Fig. 5),
+<span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_VOICE</span> (Fig. 6) and
+<span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_MYFILES</span> (Fig. 7) content categories.</p>
+
+ <p>When the <span style="font-family: Courier New,Courier,monospace">'Add attachment'</span> button of the sample application is clicked, the attach panel is displayed
+ at the bottom of the screen while the application's layout's size is adjusted to fit on the rest of the screen (see Fig. 2). The panel can be expanded
+ to fill the entire screen by swiping the minimized panel up. See Fig. 4-7 for minimized and expanded versions of the panels that were implemented in this application.</p>
+<p>The application allows you to pick or create files using Attach Panel which are later stored by the application in a gengrid. Each gengrid item
+ corresponds to a different file and is represented by a category icon (image, voice recording or file) depending on the category of Attach Panel
+ used for creating it (see Fig. 3). After an item is clicked, the default application for viewing the specified file is launched using App Common API.</p>
+
+<table>
+<col/>
+<tr>
+ <td>
+ <p class="figure">Figure 4: Image Attach Panel (minimized and expanded)</p>
+ <p align="center"><img alt="Image Attach Panel (minimized and expanded)" src="../images/attach_panel_images_panel.png" /></p>
+ </td>
+ <td>
+ <p class="figure">Figure 5: Camera Attach Panel (minimized and expanded)</p>
+ <p align="center"><img alt="Camera Attach Panel (minimized and expanded)" src="../images/attach_panel_camera_panel.png" /></p>
+ </td>
+</tr>
+<tr>
+ <td>
+ <p class="figure">Figure 6: Voice Attach Panel (minimized and expanded)</p>
+ <p align="center"><img alt="Voice Attach Panel (minimized and expanded)" src="../images/attach_panel_voice_panel.png" /></p>
+ </td>
+ <td>
+ <p class="figure">Figure 7: More Attach Panel (minimized and expanded)</p>
+ <p align="center"><img alt="More Attach Panel (minimized and expanded)" src="../images/attach_panel_more_panel.png" /></p>
+ </td>
+</tr>
+</table>
+
+<h2>Prerequisites</h2>
+<p>To ensure proper application execution, the following privileges must be specified:</p>
+ <ul>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/recorder</span> - to use <span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_VOICE</span> attachment category;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/mediastorage</span> - to use <span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_IMAGE</span> attachment category;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/camera</span> - to use <span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_CAMERA</span> attachment category;</li>
+ <li><span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/appmanager.launch</span> - to add content categories on the More tab and launch relevant apps - in case of this application, the additional category is <span style="font-family: Courier New,Courier,monospace">ATTACH_PANEL_CONTENT_CATEGORY_MYFILES</span> which corresponds to My Files app.</li>
+ </ul>
+
+<h2>Implementation</h2>
+
+<p>In order to use the Attach Panel API, you need to include the <span style="font-family: Courier New,Courier,monospace"><attach_panel.h></span> header file in your application.</p>
+
+<h3>Creating an attach panel</h3>
+
+<p>When the <span style="font-family: Courier New,Courier,monospace">'Add attachment'</span> button is clicked for the first time, the code presented in the snippet below is executed. An attach panel is created using
+<span style="font-family: Courier New,Courier,monospace">attach_panel_create()</span> function. The panel has to be anchored to the app's conformant which should be passed as the first argument to the create function.
+After the attach panel is created successfully, content categories have to be defined using <span style="font-family: Courier New,Courier,monospace">attach_panel_add_content_category()</span> function.</p>
+<p>There are two callbacks to be registered using the following functions:</p>
+<ul>
+ <li><span style="font-family: Courier New,Courier,monospace">attach_panel_set_result_cb()</span> - to get the data that the user selects from the attach panel (files' paths);</li>
+ <li><span style="font-family: Courier New,Courier,monospace">attach_panel_set_event_cb()</span> - to get notifications about events from the attach panel.</li>
+</ul>
+
+<pre class="prettyprint">
+if (attach_panel_create(vd.conform, &vd.attach_panel) != ATTACH_PANEL_ERROR_NONE) {
+ /* ... Error handling */
+}
+
+attach_panel_add_content_category(vd.attach_panel, ATTACH_PANEL_CONTENT_CATEGORY_IMAGE, NULL);
+attach_panel_add_content_category(vd.attach_panel, ATTACH_PANEL_CONTENT_CATEGORY_CAMERA, NULL);
+attach_panel_add_content_category(vd.attach_panel, ATTACH_PANEL_CONTENT_CATEGORY_VOICE, NULL);
+attach_panel_add_content_category(vd.attach_panel, ATTACH_PANEL_CONTENT_CATEGORY_MYFILES, NULL);
+
+attach_panel_set_result_cb(vd.attach_panel, __ap_result_cb, NULL);
+attach_panel_set_event_cb(vd.attach_panel, __ap_event_cb, NULL);
+</pre>
+
+
+<p>You only have to create the attach panel once during the app's execution. Its visibility can be controlled with
+<span style="font-family: Courier New,Courier,monospace">attach_panel_show()</span> and <span style="font-family: Courier New,Courier,monospace">attach_panel_hide()</span>
+functions. When the panel is created, it is hidden by default. The <span style="font-family: Courier New,Courier,monospace">attach_panel_get_visability()</span>
+function can be used to check if the panel is visible.</p>
+
+<p>The code snippet below shows what happens when the <span style="font-family: Courier New,Courier,monospace">'Add attachment'</span> button is clicked after the attach panel
+has been created. First, the panel's visability is checked. If the panel is in the hidden state, <span style="font-family: Courier New,Courier,monospace">attach_panel_show()</span>
+function is invoked to show it. The panel is hidden automatically after the user clicks the soft back key.</p>
+
+<pre class="prettyprint">
+bool visible = false;
+
+if (vd.attach_panel) {
+ if (attach_panel_get_visibility(vd.attach_panel, &visible) != ATTACH_PANEL_ERROR_NONE)
+ /* ... Error handling */
+
+ if (!visible)
+ attach_panel_show(vd.attach_panel);
+}
+</pre>
+
+<p>After the user selects or creates attachments, the <span style="font-family: Courier New,Courier,monospace">__ap_result_cb()</span> callback function is invoked. To get the files' paths,
+<span style="font-family: Courier New,Courier,monospace">app_control_get_extra_data_array()</span> function has to be invoked on the
+<span style="font-family: Courier New,Courier,monospace">app_control_h</span> result handle that is passed to the callback function. The <span style="font-family: Courier New,Courier,monospace">selected</span>
+variable is an array of strings in which the paths will be stored.</p>
+
+<pre class ="prettyprint">
+static void __ap_result_cb(attach_panel_h attach_panel, attach_panel_content_category_e content_category, app_control_h result, app_control_result_e result_code, void *user_data)
+{
+ /* ... Variables declaration */
+
+ if (app_control_get_extra_data_array(result, APPCONTROL_EXTRA_DATA_SELECTED, &selected, &length) != APP_CONTROL_ERROR_NONE) {
+ /* Error handling */
+ }
+
+ /* Check content category to set proper gengrid item's icon */
+ switch (content_category) {
+ case ATTACH_PANEL_CONTENT_CATEGORY_IMAGE:
+ case ATTACH_PANEL_CONTENT_CATEGORY_CAMERA:
+ __get_app_resource(VIEW_IMAGES_IMAGE, img_path, (int)PATH_MAX);
+ break;
+ case ATTACH_PANEL_CONTENT_CATEGORY_VOICE:
+ __get_app_resource(VIEW_IMAGES_VOICE, img_path, (int)PATH_MAX);
+ break;
+ case ATTACH_PANEL_CONTENT_CATEGORY_MYFILES:
+ __get_app_resource(VIEW_IMAGES_FILE, img_path, (int)PATH_MAX);
+ break;
+ default:
+ return;
+ }
+
+ for (; i < length; i++)
+ elm_gengrid_item_append(vd.grid, vd.gic, eina_stringshare_add(img_path), __grid_item_clicked_cb, selected[i]);
+}
+</pre>
+
+
+<h3>Launching default application for viewing a file</h3>
+<p>App Control API is used to launch the default application for viewing a file defined by URI (the file path). Below is a code snippet from the sample application
+that is responsible for that. For more information about App Control usage, see the App Control sample application or the App Control tutorial.</p>
+
+<pre class="prettyprint">
+
+void attach_panel_launch_default_view_app(char *uri)
+{
+ app_control_h service;
+
+ if (app_control_create(&service) != APP_CONTROL_ERROR_NONE)
+ /* ... Error handling */
+
+ if (app_control_set_operation(service, APP_CONTROL_OPERATION_VIEW) != APP_CONTROL_ERROR_NONE ||
+ app_control_set_operation(service, APP_CONTROL_OPERATION_VIEW) != APP_CONTROL_ERROR_NONE ||
+ app_control_set_uri(service, uri) != APP_CONTROL_ERROR_NONE ||
+ app_control_send_launch_request(service, NULL, NULL) != APP_CONTROL_ERROR_NONE) {
+ /* ... Error handling */
+ }
+
+ if (app_control_destroy(service) != APP_CONTROL_ERROR_NONE)
+ /* ... Error handling */
+}
+</pre>
+
+<script type="text/javascript" src="../scripts/jquery.zclip.min.js"></script>
+<script type="text/javascript" src="../scripts/showhide.js"></script>
+</div></div></div>
+
+<a class="top sms" href="#"><img src="../images/btn_top.gif" alt="Go to top" /></a>
+
+<div id="footer">
+<p class="footer">Except as noted, this content - excluding the Code Examples - is licensed under <a href="http://creativecommons.org/licenses/by/3.0/legalcode" target="_blank">Creative Commons Attribution 3.0</a> and all of the Code Examples contained herein are licensed under <a href="https://www.tizen.org/bsd-3-clause-license" target="_blank">BSD-3-Clause</a>.<br/>For details, see the <a href="https://www.tizen.org/content-license" target="_blank">Content License</a>.</p>
+</div>
+
+<script type="text/javascript">
+var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-25976949-1']);
+_gaq.push(['_trackPageview']);
+(function() {
+var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();
+</script>
+
+</body>
+</html>
projects / sdk / online-doc.git / commitdiff
