Introduction

The Tizen Native API gives the possibility to display and manage calendars. There are two types of calendar entities: events and ‘to-dos’. Our article series regards only the second type.

The first part of this article series describes how to connect to the calendar service and create an example task. The second part will describe getting to-do tasks and updating their properties.

Sample application

CustomOrganizer is a simple Tizen Native application. The first view (figure 1) displays a list of non-completed tasks for the selected day (start date for this task <= selected date). You can set the selected task as completed or edit its properties. The second view (figure 2) displays an Edit view. For each task you can change its status and start date.

The sample application is compatible with Tizen SDK 2.3 Rev2.

Starting with...

Firstly, you need to know that our to-dos are stored in a system calendar. To manage them you have to use the Calendar API. To do that it’s necessary to include the <calendar.h> header file in your application and add some privileges to the application manifest:

<privilege>http://tizen.org/privilege/calendar.read</privilege>
<privilege>http://tizen.org/privilege/calendar.write</privilege>

To get access to the calendar database you need to connect to the Calendar Service:

// Connect with calendar
error_code = calendar_connect();
if (error_code != CALENDAR_ERROR_NONE)
    dlog_print(DLOG_ERROR, LOG_TAG, "calendar_connect: %d\n", error_code);

If everything goes fine, the function will return zero. Otherwise it returns a negative value. There are lots of functions returning error codes in Tizen Native API. Remember to verify the value returned by the function.

After performing all wanted operations, the connection with Calendar Service should be closed in the following way:

error_code = calendar_disconnect();
if (error_code != CALENDAR_ERROR_NONE)
    dlog_print(DLOG_ERROR, LOG_TAG, "calendar disconnect failed: %x\n", error_code);

The execution of opening and closing connections with the calendar database can slow down your application, so don't call these functions frequently.

Getting a list of to-dos

At the beginning the sample application checks if your calendar contains any to-dos:

error_code = calendar_db_get_all_records(_calendar_todo._uri, 0, 0, &list);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "db get all records failed: %d\n", error_code);

error_code = calendar_list_get_count(list, &count);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_list_get_count failed: %d\n", error_code);

The calendar_list_get_count() function returns the number of to-do tasks in a calendar list. However it can’t be only completed tasks, so the next function checks if you have any uncompleted tasks:

if (count != 0)
    while (calendar_list_get_current_record_p(list, &recordOut) == CALENDAR_ERROR_NONE)
    {
        status = 0;
        count = 0;

        // Get record status
        calendar_record_get_int(recordOut, _calendar_todo.todo_status, &status);
        dlog_print(DLOG_INFO, LOG_TAG, "app_create task status: %d\n", status);
        if (status != CALENDAR_TODO_STATUS_COMPLETED && status != CALENDAR_TODO_STATUS_CANCELED) {
            count++;
        }

        error_code = calendar_list_next(list);
        if (error_code != CALENDAR_ERROR_NONE)
            break;
    }

It doesn't make sense to run this sample application with no tasks so if you don't have any (e.g. because you test this application on the emulator), the application will create some.

Creating a to-do task

The create_test_todo_task() function creates 7 to-do tasks with a specified name (in the following form: “Task1”, “Task2”, etc.) and start date (today, today + 1, today + 2, etc.). The status of a newly created task is set to “in progress” and calendar type to “DEFAULT_TODO_CALENDAR_BOOK_ID”.

#define SECONDS_IN_DAY      (24*60*60)
 (…)

if (count == 0) {
    char str[2];
    int y, m, d;

    // Get actual date
    i18n_ucalendar_h ucalendar = getToday();

    // gets the current value of a field from i18n_ucalendar_h
    i18n_ucalendar_get(ucalendar, I18N_UCALENDAR_YEAR, &y);
    i18n_ucalendar_get(ucalendar, I18N_UCALENDAR_MONTH, &m);
    i18n_ucalendar_get(ucalendar, I18N_UCALENDAR_DATE, &d);

    long long int x = _time_convert_itol(NULL, y, m, d);

    for (int i = 0; i < 7; i++) {
        sprintf(str, "Task%d", i);
        create_test_todo_task(str, x);
        x += SECONDS_IN_DAY;
    }
}

The _time_convert_itol() function is described in details in the Documentation (Tizen Mobile Native App Programming > API Reference > Native API Reference > Social > Calendar). For a given year, month and day it gives the number of seconds elapsed since Thursday, 1 January 1970, 00:00:00 UTC.

To get a new to-do task create a to-do record handle using the calendar_record_create() function:

calendar_record_h todo = NULL;

/* URI */
error_code = calendar_record_create(_calendar_todo._uri, &todo);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "calendar_record_create: %x\n", error_code);

At the end (after setting the necessary properties) you must release the given record handle (calendar_record_h todo) using the calendar_record_destroy() function:

 (...)

/* ...and destroy a record handle */
calendar_record_destroy(todo, true);

Note: Please, remember that you need to call the calendar_connect() function before performing other operations on the calendar database.

We have the record handle, so we can use it to set the created to-do’s properties. For this purpose we use one of following five functions:

The function used depends on the type of value we want to set (string, int, long long int, etc.). E.g. setting a short description for a to-do requires using the calendar_record_set_str() function.

The second argument of the function is the property id of the to-do task, e.g. summary, todo_status, etc. A full list of to-do’s properties can be found in the Documentation (Tizen Mobile Native App Programming > API Reference > Native API Reference > Social > Calendar>View/Property for _calendar_todo view).

calendar_time_s start_time = {0};
int calendar_type = DEFAULT_TODO_CALENDAR_BOOK_ID;
int id = 0;
int todo_status = CALENDAR_TODO_STATUS_IN_PROCESS;

(...)
/* Summary */
error_code = calendar_record_set_str(todo, _calendar_todo.summary, summary);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "set summary failed : %x\n", error_code);

/* Start time */
start_time.type = CALENDAR_TIME_UTIME;

// utime in seconds
start_time.time.utime = startTime;

error_code = calendar_record_set_caltime(todo, _calendar_todo.start_time, start_time);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "set due_time failed : %x\n", error_code);

/* Status */
error_code = calendar_record_set_int(todo, _calendar_todo.todo_status, todo_status);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "set todo_status failed : %x\n", error_code);

/* Book Id */
error_code = calendar_record_set_int(todo, _calendar_todo.calendar_book_id, calendar_type);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "set calendar_book_id failed: %x\n", error_code);

Finally, the created to-do record is inserted into the calendar database:

/* Insert record into db... */
error_code = calendar_db_insert_record(todo, &id);
if (error_code != CALENDAR_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "db insert record failed: %d\n", error_code);

Remember to release the to-do record handle at the end using calendar_record_destroy() function.

Summary

This is the end of the first part of this article series. The next article will describe how to get properties of to-do tasks from the calendar database and how to update them.

More information about Calendar API and its usage can be found in Documentation:

Tizen Mobile Native App Programming > Tutorials > Social Tutorials > Calendar Tutorial

Tizen Mobile Native App Programming > Programming Guide > Social: Managing Personal Data > Calendar

Tizen Mobile Native App Programming > API Reference > Native API Reference > Social > Calendar