Watch Face Complication

The complication shows key information from an application in an economical way. You can tap complications to open the corresponding application and see more detailed information.

The complication data is provided from the complication provider application and the watch face application decides how to display the complications using that data. The watch face can select the complication and request to update the complication to the complication provider application.

There are two ways to update the complication data.

1. Watch Face can request complication provider application to update complication data. The complication provider application receives the request and updates the complication data. Then, the complication update callback is called in watch face.

   

2. If the complication data is changed, the complication provider application can notify to the watch face. If the complication receives the notification, it requests to update automatically. Then, the update request comes to the complication provider. The complication provider must set the updated data in update requested callback. After the complication data is updated, the complication update callback is called in the watch face.

   

Types of Watch Face Complication

The complication support type is the types of data that can be provided from complication provider. The complication provider have to support at least one type. In addition, one complication provider can support multiple types. Watch Face can set the complication support types to support specific type of complications.

The followings are types of watch face complication:

Prerequisites

1. To use the Watch Face Complication API, the application has to request permission by adding the following privilege to the tizen-manifest.xml file:

   <privileges>
   	<privilege>http://tizen.org/privilege/datasharing</privilege>
   	<privilege>http://tizen.org/privilege/appmanager.launch</privilege>
   </privileges>
   

2. To use the functions and data types for the Watch Face Complication API, include the <watchface-complication.h> header file in application:

   #include <watchface-complication.h>
   

Creating Watch Face Complication

Watch Face must create the complication handle to add the default complication. You can choose the support types of complication that can be selected in the position of complication. And also choose the touch event type that can be supported.

{
	int ret;
	int comp_id = 1;
	complication_h complication;

	ret = watchface_complication_create(comp_id, "org.tizen.sample",
			WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT,
			WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT|WATCHFACE_COMPLICATION_TYPE_ICON,
			WATCHFACE_COMPLICATION_EVENT_TAP, &complication);
}

The default provider id and type are the items to set for initial display. As the default provider they must not be null. If they are null, the complication receives an error. Also, if you select the other provider and type, that they are no longer used.

Updating Complication Data

To receive the updated complication data, watchface_complication_updated_cb() must be added in the watch face by using watchface_complication_add_updated_cb(). And, if complication provider is not available (disabled, uninstalled), watchface_complication_error_cb() is called. In this case, watch face can add fallback logic in error callback such as display error message or launch editor interface.

void _watchface_complication_updated_cb(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
}

void _watchface_complication_error_cb)(
		int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		watchface_complication_error_e error,
		void *user_data)
{
}

static void _init_complication()
{
	watchface_complication_add_updated_cb(complication,
		_watchface_complication_updated_cb,
		_watchface_complication_error_cb,  NULL);
}

When the complication provider data is updated, watchface_complication_updated_cb() is called. Watch Face can get the information from the bundle parameter of callback by using watchface_complication_data_get_*.

To get the complication provider data, the following functions can be used:

Note

watchface_complication_data_get_timestamp() is deprecated since Tizen 5.5. Instead, use watchface_complication_data_get_timeinfo().

void _watchface_complication_updated_cb(int complication_id,
		const char *provider_id,
		watchface_complication_type_e type,
		const bundle *data, void *user_data)
{
	char *shorttext = NULL;
	time_t timestamp;
	complication_time_info_h info;
	char *country = NULL;
	char *city = NULL;
	char *id = NULL;

	if (type == WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT) {
		watchface_complication_data_get_short_text(data, &shorttext);
	} else if (type == WATCHFACE_COMPLICATION_TYPE_TIME) {
		watchface_complication_data_get_timeinfo(data, &info);
		watchface_complication_timeinfo_get_timezone_id(info, &id);
		watchface_complication_timeinfo_get_timezone_city(info, &city);
		watchface_complication_timeinfo_get_timezone_country(info, &country);
		watchface_complication_timeinfo_get_timestamp(info, &timestamp);
		watchface_complication_timeinfo_destroy(info);
	}

	if (shorttext)
		free(shorttext);
	if (country)
		free(country);
	if (city)
		free(city);
	if (id)
		free(id);
}

If the callback is not used any more, it must be removed by using watchface_complication_remove_updated_cb():

{
	watchface_complication_remove_updated_cb(complication,
		_watchface_complication_updated_cb);
}

If the watch face wants the updated complication data, watch face can request to update the data to the complication provider:

{
	watchface_complication_send_update_request(complication);
}

Specifying to Support only Specific Complication Provider

Watch Face can support the specific complication provider by using allowed_list. In This case, watch face supports complications only in allowed complication list:

{
	complication_allowed_list_h allowed_list;

	watchface_complication_allowed_list_create(&allowed_list);
	watchface_complication_allowed_list_add(allowed_list, "PROVIDER_ID_1",
			WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT);
	watchface_complication_allowed_list_add(allowed_list, "PROVIDER_ID_2",
			WATCHFACE_COMPLICATION_TYPE_SHORT_TEXT);
	watchface_complication_allowed_list_apply(complication, allowed_list);

	watchface_complication_allowed_list_destroy(allowed_list);
}

Watch Face Edit with Editable Feature

The watch face application can provide the changeable features (such as, complication, color, font, and so on) with watch face editable APIs.

The features can be changed by watch face editor application:

1. To use the functions and data types for the Watch Face Editable API, include the <watchface-editable.h> header file in your application:

   #include <watchface-editable.h>
   

2. When the editor is ready to edit, it notifies that it is ready. To receive the notification from the editor, watchface_editable_edit_ready_cb() must be added:

   void _watchface_editable_edit_ready_cb(watchface_editable_container_h handle,
   		const char *editor_appid,
   		void *user_data)
   {
   }
   
   {
   	watchface_editable_add_edit_ready_cb(_watchface_editable_edit_ready_cb, NULL);
   }
   

3. Watch Face can create the complication_candidates_list_h to identify the editable features to request to editor. Watch Face can request to edit the features by using watchface_editable_request_edit().

4. The watch face editor can draw highlight to give the information about editing. To inform the position of editable features, watchface_editable_highlight_h must be used. The highlight handle can be created by watchface_editable_highlight_create() with watch face shape type.

   The following are shape types:

   Shape types	Description
   WATCHFACE_EDITABLE_SHAPE_TYPE_CIRCLE	circle
   WATCHFACE_EDITABLE_SHAPE_TYPE_RECT	rectangle

   The position of editable feature can be set by using watchface_editable_highlight_set_geometry(). The parameters of this function means the position(x,y) and size(width, height).

   Note

   watchface_editable_highlight_h must be released. It can be released by using watchface_editable_highlight_destroy().

5. According to the editable feature, watchface_editable_add_design_element() and watchface_editable_add_complication() are used to add editable features to the watchface_editable_container_h.

   static void _watchface_editable_edit_ready_cb(watchface_editable_container_h handle,
   		const char *editor_appid, void *user_data)
   {
   	bundle *candidate1;
   	bundle *candidate2;
   	complication_h comp;
   	watchface_editable_highlight_h hi;
   	complication_candidates_list_h candidates_list = NULL;
   
   	watchface_editable_candidates_list_create(&candidates_list);
   
   	candidate1 = bundle_create();
   	bundle_add_str(candidate1, "TEST_COLOR", "RED");
   	watchface_editable_candidates_list_add(candidates_list, candidate1);
   	bundle_free(candidate1);
   
   	candidate2 = bundle_create();
   	bundle_add_str(candidate2, "TEST_COLOR", "YELLOW");
   	watchface_editable_candidates_list_add(candidates_list, candidate2);
   	bundle_free(candidate2);
   
   	watchface_editable_highlight_create(&hi, WATCHFACE_EDITABLE_SHAPE_TYPE_CIRCLE);
   	watchface_editable_highlight_set_geometry(hi, 50, 50, 100, 100);
   	watchface_editable_add_design_element(handle, COLOR_EDIT, cur_idx, candidates_list, hi, "Color");
   	watchface_editable_highlight_destroy(hi);
   
   	watchface_editable_candidates_list_destroy(list_handle);
   
   	watchface_editable_highlight_create(&hi, WATCHFACE_EDITABLE_SHAPE_TYPE_CIRCLE);
   	watchface_editable_highlight_set_geometry(hi, 100, 100, 100, 100);
   	watchface_editable_add_complication(handle, comp_id, comp, hi);
   	watchface_editable_highlight_destroy(hi);
   
   	watchface_editable_request_edit(handle, _watchface_editable_update_requested_cb, user_data);
   }
   

6. If some features are changed from editor, watchface_editable_update_requested_cb() is called. Watch Face can verify the watchface_editable_edit_state_e from the parameter of that callback to get the edit state.

   The following are the edit state:

   Edit state	Description
   WATCHFACE_EDITABLE_EDIT_STATE_COMPLETE	edit complete
   WATCHFACE_EDITABLE_EDIT_STATE_ONGOING	ongoing edit
   WATCHFACE_EDITABLE_EDIT_STATE_CANCEL	edit canceled

   static void _watchface_editable_update_requested_cb(const watchface_editable_h handle,
   		int selected_idx,
   		const watchface_editable_edit_state_e state,
   		void *user_data)
   {
   	bundle *data;
   	int ed_id;
   
   	watchface_editable_get_current_data(handle, &data);
   	watchface_editable_get_editable_id(handle, &ed_id);
   
   }
   

Transferring Touch Event

Complication can provide additional action for touching when the complication is touched. To trigger the complication touch action, watch face must transfer the touch event to complication provider when the complication is touched.

The following are event types:

Watch Face transfers by using watchface_complication_transfer_event():

void _on_complication_clicked(complication_h handle)
{
	watchface_complication_transfer_event(handle, WATCHFACE_COMPLICATION_EVENT_TAP);
}

Related Information

• Dependencies
  • Tizen 5.0 and Higher for Wearable