+ +

Attach Panel Sample Overview

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.

+ + ++ + + + + +

Figure 1: Attach Panel sample app main view

Attach Panel sample app main view

Figure 2: Attach Panel sample app view with the attach panel visible

Attach Panel sample app view with the attach panel visible

Figure 3: Attach Panel sample app view with filled attachment's gengrid

Attach Panel sample app view with filled attachment's gengrid

+ +

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.

+ +

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:

ATTACH_PANEL_CONTENT_CATEGORY_IMAGE - attach images from Gallery;
ATTACH_PANEL_CONTENT_CATEGORY_CAMERA - take a picture to be attached;
ATTACH_PANEL_CONTENT_CATEGORY_VOICE - record an audio file to be attached;
ATTACH_PANEL_CONTENT_CATEGORY_VIDEO - attach video files from Gallery;
ATTACH_PANEL_CONTENT_CATEGORY_AUDIO - attach audio files from My Files;
ATTACH_PANEL_CONTENT_CATEGORY_CALENDAR - attach calendar data from Calendar;
ATTACH_PANEL_CONTENT_CATEGORY_CONTACT - attach contact data from Contacts;
ATTACH_PANEL_CONTENT_CATEGORY_MYFILES - attach files from My Files;
ATTACH_PANEL_CONTENT_CATEGORY_VIDEO_RECORDER - record a video file to be attached.

+ +

This sample application uses ATTACH_PANEL_CONTENT_CATEGORY_IMAGE (Fig. 4), +ATTACH_PANEL_CONTENT_CATEGORY_CAMERA (Fig. 5), +ATTACH_PANEL_CONTENT_CATEGORY_VOICE (Fig. 6) and +ATTACH_PANEL_CONTENT_CATEGORY_MYFILES (Fig. 7) content categories.

+ +

When the 'Add attachment' 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.

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.

+ + ++ + + + + + + + +

Figure 4: Image Attach Panel (minimized and expanded)

Image Attach Panel (minimized and expanded)

Figure 5: Camera Attach Panel (minimized and expanded)

Camera Attach Panel (minimized and expanded)

Figure 6: Voice Attach Panel (minimized and expanded)

Voice Attach Panel (minimized and expanded)

Figure 7: More Attach Panel (minimized and expanded)

More Attach Panel (minimized and expanded)

+ +

Prerequisites

To ensure proper application execution, the following privileges must be specified:

http://tizen.org/privilege/recorder - to use ATTACH_PANEL_CONTENT_CATEGORY_VOICE attachment category;
http://tizen.org/privilege/mediastorage - to use ATTACH_PANEL_CONTENT_CATEGORY_IMAGE attachment category;
http://tizen.org/privilege/camera - to use ATTACH_PANEL_CONTENT_CATEGORY_CAMERA attachment category;
http://tizen.org/privilege/appmanager.launch - to add content categories on the More tab and launch relevant apps - in case of this application, the additional category is ATTACH_PANEL_CONTENT_CATEGORY_MYFILES which corresponds to My Files app.

+ +

Implementation

+ +

In order to use the Attach Panel API, you need to include the <attach_panel.h> header file in your application.

+ +

Creating an attach panel

+ +

When the 'Add attachment' button is clicked for the first time, the code presented in the snippet below is executed. An attach panel is created using +attach_panel_create() 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 attach_panel_add_content_category() function.

There are two callbacks to be registered using the following functions:

attach_panel_set_result_cb() - to get the data that the user selects from the attach panel (files' paths);
attach_panel_set_event_cb() - to get notifications about events from the attach panel.

+ +

+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);
+

+ + +

You only have to create the attach panel once during the app's execution. Its visibility can be controlled with +attach_panel_show() and attach_panel_hide() +functions. When the panel is created, it is hidden by default. The attach_panel_get_visability() +function can be used to check if the panel is visible.

+ +

The code snippet below shows what happens when the 'Add attachment' 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, attach_panel_show() +function is invoked to show it. The panel is hidden automatically after the user clicks the soft back key.

+ +

+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);
+}
+

+ +

After the user selects or creates attachments, the __ap_result_cb() callback function is invoked. To get the files' paths, +app_control_get_extra_data_array() function has to be invoked on the +app_control_h result handle that is passed to the callback function. The selected +variable is an array of strings in which the paths will be stored.

+ +

+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]);
+}
+

+ + +

Launching default application for viewing a file

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.

+ +

+   
+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 */
+}
+

+ + + +