Timeline

Pins, notifications and reminders, their attributes, actions and layouts. More...

Modules
	Timeline action endpoint
	Pebble Protocol endpoint 0x2cb0 for actions executed by the phone.
	Alarm layout
	Layout of alarm pins (LayoutIdAlarm).
	Timeline attributes
	Typed key/value attributes describing timeline items and actions.
	Attribute groups
	Shared code for data made of an attribute list and a group of elements with their own attributes.
	Serialized attributes
	Wire format of a timeline attribute.
	Attributes and actions
	Storage and serialization of an attribute list with an action group.
	Calendar events
	Tracks whether a calendar event is ongoing.
	Calendar layout
	Layout of calendar pins (LayoutIdCalendar).
	Calendar layout icons
	Vector icons next to the start and end times on calendar cards.
	Timeline events
	Tracks the next or current timeline event for services that react to it.
	Generic layout
	Layout of generic pins (LayoutIdGeneric).
	Health layout
	Layout of health pins (LayoutIdHealth) and Health app launch arguments.
	Timeline items
	Pins, notifications and reminders.
	Layout layers
	Layers that render templated content such as timeline items.
	Layout nodes
	Compact, declarative construction of GTextNode trees for layouts.
	Metric groups
	Builder for the metric names, values and icons attributes of a pin.
	Jumboji table
	Emoji shown large ("Jumboji") when a notification body is just that emoji.
	Notification layout
	Layout of notifications and reminders (LayoutIdNotification, LayoutIdReminder).
	Timeline Peek events
	Selects the event shown by Timeline Peek.
	Reminders
	Pops up reminders at their time.
	Sports layout
	Layout of sports pins (LayoutIdSports).
	Swap layer
	Scrolls through a sequence of layouts, swapping to the previous or next at the ends.
	Timeline action menus
	Action menus for timeline items and the handling of action results.
	Timeline layouts
	Common base of the pin layouts (generic, calendar, weather, sports, alarm, health).
	Timeline layout animations
	Icon transitions between the pin and card views of a timeline item.
	Timeline resources
	Resolves timeline resource ids to image resources.
	Weather layout
	Layout of weather pins (LayoutIdWeather).

Data Structures
struct	TimelineIterState
	State of a timeline iterator. More...

Macros
#define	UUID_NOTIFICATIONS_DATA_SOURCE    {0xed, 0x42, 0x9c, 0x16, 0xf6, 0x74, 0x42, 0x20, 0x95, 0xda, 0x45, 0x4f, 0x30, 0x3f, 0x15, 0xe2}
	Data source of notifications, ed429c16-f674-4220-95da-454f303f15e2.
#define	UUID_CALENDAR_DATA_SOURCE    {0x6c, 0x6c, 0x6f, 0xc2, 0x19, 0x12, 0x4d, 0x25, 0x83, 0x96, 0x35, 0x47, 0xd1, 0xdf, 0xac, 0x5b}
	Data source of calendar pins, 6c6c6fc2-1912-4d25-8396-3547d1dfac5b.
#define	UUID_WEATHER_DATA_SOURCE    {0x61, 0xb2, 0x2b, 0xc8, 0x1e, 0x29, 0x46, 0xd, 0xa2, 0x36, 0x3f, 0xe4, 0x9, 0xa4, 0x39, 0xff}
	Data source of weather pins, 61b22bc8-1e29-460d-a236-3fe409a439ff.
#define	UUID_REMINDERS_DATA_SOURCE    {0x42, 0xa0, 0x72, 0x17, 0x54, 0x91, 0x42, 0x67, 0x90, 0x4a, 0xd0, 0x2a, 0x15, 0x67, 0x52, 0xb6}
	Data source of reminders, 42a07217-5491-4267-904a-d02a156752b6.
#define	UUID_ALARMS_DATA_SOURCE    {0x67, 0xa3, 0x2d, 0x95, 0xef, 0x69, 0x46, 0xd4, 0xa0, 0xb9, 0x85, 0x4c, 0xc6, 0x2f, 0x97, 0xf9}
	Data source of alarm pins, 67a32d95-ef69-46d4-a0b9-854cc62f97f9.
#define	UUID_HEALTH_DATA_SOURCE    {0x36, 0xd8, 0xc6, 0xed, 0x4c, 0x83, 0x4f, 0xa1, 0xa9, 0xe2, 0x8f, 0x12, 0xdc, 0x94, 0x1f, 0x8c}
	Data source of health pins, 36d8c6ed-4c83-4fa1-a9e2-8f12dc941f8c.
#define	UUID_WORKOUT_DATA_SOURCE    {0xfe, 0xf8, 0x2c, 0x82, 0x71, 0x76, 0x4e, 0x22, 0x88, 0xde, 0x35, 0xa3, 0xfc, 0x18, 0xd4, 0x3f}
	Data source of workout pins, fef82c82-7176-4e22-88de-35a3fc18d43f.
#define	UUID_SEND_TEXT_DATA_SOURCE    {0x08, 0x63, 0xfc, 0x6a, 0x66, 0xc5, 0x4f, 0x62, 0xab, 0x8a, 0x82, 0xed, 0x00, 0xa9, 0x8b, 0x5d}
	Data source of the Send Text app, 0863fc6a-66c5-4f62-ab8a-82ed00a98b5d.
#define	UUID_SEND_SMS    {0x0f, 0x71, 0xaa, 0xba, 0x58, 0x14, 0x4b, 0x5c, 0x96, 0xe2, 0xc9, 0x82, 0x8c, 0x97, 0x34, 0xcb}
	Item id that lets the watch send an SMS to a phone number, 0f71aaba-5814-4b5c-96e2-c9828c9734cb.
#define	UUID_INTERCOM_DATA_SOURCE    {0x68, 0x01, 0x06, 0x69, 0x4b, 0x38, 0x47, 0x51, 0xad, 0x04, 0x06, 0x7f, 0x1d, 0x8d, 0x2a, 0xb5}
	Data source of intercom pins, 68010669-4b38-4751-ad04-067f1d8d2ab5.

Typedefs
typedef struct TimelineNode	TimelineNode
	Opaque node of the ordered pin list.

Enumerations
enum	TimelineIterDirection { TimelineIterDirectionPast , TimelineIterDirectionFuture }
	Direction of a timeline iteration. More...

Functions
status_t	timeline_init (TimelineNode **timeline)
	Build the ordered pin list from the Pins database.
bool	timeline_add (TimelineItem *item)
	Add a pin created on the watch to the Pins database.
bool	timeline_add_missed_call_pin (TimelineItem *pin, uint32_t uid)
	Add a missed call pin.
bool	timeline_remove (const Uuid *id)
	Remove a pin through BlobDB, which emits a BlobDB delete event.
bool	timeline_exists (Uuid *id)
	Check whether a pin exists.
void	timeline_enable_ancs_bulk_action_mode (bool enable)
	Enable or disable bulk mode for ANCS actions.
bool	timeline_is_bulk_ancs_action_mode_enabled (void)
	Check whether bulk mode for ANCS actions is enabled.
void	timeline_invoke_action (const TimelineItem *item, const TimelineItemAction *action, const AttributeList *attributes)
	Invoke an action of a timeline item.
TimelineIterDirection	timeline_direction_for_item (TimelineItem *item, TimelineNode *timeline, time_t now)
	Get the direction in which a pin is shown.
bool	timeline_nodes_equal (TimelineNode *a, TimelineNode *b)
	Compare two nodes.
bool	timeline_get_originator_id (const TimelineItem *item, Uuid *id)
	Get the UUID of the originator of a timeline item.
int	timeline_item_time_comparator (CommonTimelineItemHeader *new_common, CommonTimelineItemHeader *old_common, TimelineIterDirection direction)
	Compare items in Timeline order, ignoring all-day events.
bool	timeline_item_should_show (CommonTimelineItemHeader *header, TimelineIterDirection direction)
	Check whether an item shows up in a Timeline direction, ignoring all-day events.
status_t	timeline_iter_init (Iterator *iter, TimelineIterState *iter_state, TimelineNode **timeline, TimelineIterDirection direction, time_t timestamp)
	Start iterating over the pin list.
void	timeline_iter_copy_state (TimelineIterState *dst_state, TimelineIterState *src_state, Iterator *dst_iter, Iterator *src_iter)
	Copy an iterator into another one.
void	timeline_iter_deinit (Iterator *iter, TimelineIterState *iter_state, TimelineNode **head)
	Free the pin list and the iterator's current pin.
void	timeline_iter_refresh_pin (TimelineIterState *iter_state)
	Reload the current pin from the Pins database.
void	timeline_iter_remove_node (TimelineNode **timeline, TimelineNode *node)
	Remove a node from the pin list.
bool	timeline_iter_remove_node_with_id (TimelineNode **timeline, Uuid *key)
	Remove the first node with an id from the pin list.
const char *	timeline_get_private_data_source (Uuid *parent_id)
	Get the name of a private (non-app) data source such as Weather or Calendar.

Detailed Description

Pins, notifications and reminders, their attributes, actions and layouts.

Every timeline entity is a TimelineItem (Timeline items): a common header plus a list of typed attributes (Timeline attributes) and a group of actions. Pins are kept in the Pins BlobDB, reminders in the Reminders BlobDB and notifications in notification storage. Items are rendered by layouts (Layout layers) chosen by the header's LayoutId.

This header manages pins: adding and removing them, invoking actions, and iterating over the pins shown in the Timeline app. The iterator walks a time-ordered list of TimelineNode built by timeline_init(); all-day events come first, then events by start time, and an event appears in both the past and the future until it ends. Only pins within two days in the past and three days in the future are visited.

TimelineNode *timeline = NULL;
Iterator iter;
TimelineIterState state = {0};
 
timeline_init(&timeline);
if (timeline_iter_init(&iter, &state, &timeline, TimelineIterDirectionFuture, rtc_get_time()) ==
    S_SUCCESS) {
  do {
    const char *title = attribute_get_string(&state.pin.attr_list, AttributeIdTitle, "");
    ...
  } while (iter_next(&iter));
}
timeline_iter_deinit(&iter, &state, &timeline);

---

Data Structure Documentation

TimelineIterState

struct TimelineIterState

State of a timeline iterator.

Data Fields
time_t	current_day	Midnight of the day of the current pin.
TimelineIterDirection	direction	Direction of the iteration.
int	index	Index of the current node in the list.
time_t	midnight	Midnight of the day of start_time.
TimelineNode *	node	Current node.
TimelineItem	pin	Current pin, read from the Pins database; its buffer is owned by the iterator.
bool	show_all_day_events	Whether all-day events are shown in this direction.
time_t	start_time	Time the iteration started from.

Macro Definition Documentation

UUID_ALARMS_DATA_SOURCE

#define UUID_ALARMS_DATA_SOURCE    {0x67, 0xa3, 0x2d, 0x95, 0xef, 0x69, 0x46, 0xd4, 0xa0, 0xb9, 0x85, 0x4c, 0xc6, 0x2f, 0x97, 0xf9}

Data source of alarm pins, 67a32d95-ef69-46d4-a0b9-854cc62f97f9.

UUID_CALENDAR_DATA_SOURCE

#define UUID_CALENDAR_DATA_SOURCE    {0x6c, 0x6c, 0x6f, 0xc2, 0x19, 0x12, 0x4d, 0x25, 0x83, 0x96, 0x35, 0x47, 0xd1, 0xdf, 0xac, 0x5b}

Data source of calendar pins, 6c6c6fc2-1912-4d25-8396-3547d1dfac5b.

UUID_HEALTH_DATA_SOURCE

#define UUID_HEALTH_DATA_SOURCE    {0x36, 0xd8, 0xc6, 0xed, 0x4c, 0x83, 0x4f, 0xa1, 0xa9, 0xe2, 0x8f, 0x12, 0xdc, 0x94, 0x1f, 0x8c}

Data source of health pins, 36d8c6ed-4c83-4fa1-a9e2-8f12dc941f8c.

UUID_INTERCOM_DATA_SOURCE

#define UUID_INTERCOM_DATA_SOURCE    {0x68, 0x01, 0x06, 0x69, 0x4b, 0x38, 0x47, 0x51, 0xad, 0x04, 0x06, 0x7f, 0x1d, 0x8d, 0x2a, 0xb5}

Data source of intercom pins, 68010669-4b38-4751-ad04-067f1d8d2ab5.

UUID_NOTIFICATIONS_DATA_SOURCE

#define UUID_NOTIFICATIONS_DATA_SOURCE    {0xed, 0x42, 0x9c, 0x16, 0xf6, 0x74, 0x42, 0x20, 0x95, 0xda, 0x45, 0x4f, 0x30, 0x3f, 0x15, 0xe2}

Data source of notifications, ed429c16-f674-4220-95da-454f303f15e2.

UUID_REMINDERS_DATA_SOURCE

#define UUID_REMINDERS_DATA_SOURCE    {0x42, 0xa0, 0x72, 0x17, 0x54, 0x91, 0x42, 0x67, 0x90, 0x4a, 0xd0, 0x2a, 0x15, 0x67, 0x52, 0xb6}

Data source of reminders, 42a07217-5491-4267-904a-d02a156752b6.

UUID_SEND_SMS

#define UUID_SEND_SMS    {0x0f, 0x71, 0xaa, 0xba, 0x58, 0x14, 0x4b, 0x5c, 0x96, 0xe2, 0xc9, 0x82, 0x8c, 0x97, 0x34, 0xcb}

Item id that lets the watch send an SMS to a phone number, 0f71aaba-5814-4b5c-96e2-c9828c9734cb.

UUID_SEND_TEXT_DATA_SOURCE

#define UUID_SEND_TEXT_DATA_SOURCE    {0x08, 0x63, 0xfc, 0x6a, 0x66, 0xc5, 0x4f, 0x62, 0xab, 0x8a, 0x82, 0xed, 0x00, 0xa9, 0x8b, 0x5d}

Data source of the Send Text app, 0863fc6a-66c5-4f62-ab8a-82ed00a98b5d.

UUID_WEATHER_DATA_SOURCE

#define UUID_WEATHER_DATA_SOURCE    {0x61, 0xb2, 0x2b, 0xc8, 0x1e, 0x29, 0x46, 0xd, 0xa2, 0x36, 0x3f, 0xe4, 0x9, 0xa4, 0x39, 0xff}

Data source of weather pins, 61b22bc8-1e29-460d-a236-3fe409a439ff.

UUID_WORKOUT_DATA_SOURCE

#define UUID_WORKOUT_DATA_SOURCE    {0xfe, 0xf8, 0x2c, 0x82, 0x71, 0x76, 0x4e, 0x22, 0x88, 0xde, 0x35, 0xa3, 0xfc, 0x18, 0xd4, 0x3f}

Data source of workout pins, fef82c82-7176-4e22-88de-35a3fc18d43f.

Typedef Documentation

TimelineNode

typedef struct TimelineNode TimelineNode

Opaque node of the ordered pin list.

Enumeration Type Documentation

TimelineIterDirection

enum TimelineIterDirection

Direction of a timeline iteration.

Enumerator
TimelineIterDirectionPast	Towards older pins.
TimelineIterDirectionFuture	Towards newer pins.

Function Documentation

timeline_add()

bool timeline_add

(

TimelineItem *

item

)

Add a pin created on the watch to the Pins database.

The item is serialized, so destroy it with timeline_item_destroy() afterwards.

Parameters

item	Pin to add.

Returns

true on success.

timeline_add_missed_call_pin()

bool timeline_add_missed_call_pin	(	TimelineItem *	pin,
		uint32_t	uid
	)

Add a missed call pin.

Gives pin a new id, the generic layout and the from-watch flag, and turns its dismiss action into a remove action.

Parameters

pin	Pin built from the missed call notification; it must have a dismiss action.
uid	ANCS UID of the missed call notification.

Returns

true on success.

timeline_direction_for_item()

TimelineIterDirection timeline_direction_for_item	(	TimelineItem *	item,
		TimelineNode *	timeline,
		time_t	now
	)

Get the direction in which a pin is shown.

Parameters

item	Pin.
timeline	Ordered pin list, used to place all-day events.
now	Current time.

Returns

TimelineIterDirectionPast if the pin is in the past, TimelineIterDirectionFuture otherwise.

timeline_enable_ancs_bulk_action_mode()

void timeline_enable_ancs_bulk_action_mode

(

bool

enable

)

Enable or disable bulk mode for ANCS actions.

In bulk mode ANCS dismiss actions do not post a result dialog for each item, so dismissing many items does not fill the event queue.

Parameters

enable

true to enable.

timeline_exists()

bool timeline_exists

(

Uuid *

id

)

Check whether a pin exists.

Parameters

id	Id of the pin.

Returns

true if it exists in the Pins database.

timeline_get_originator_id()

bool timeline_get_originator_id	(	const TimelineItem *	item,
		Uuid *	id
	)

Get the UUID of the originator of a timeline item.

For pins and notifications this is the parent_id of the item, or of its parent pin if it has one, i.e. the app UUID (pins) or source id (notifications). For reminders it is the parent_id of the parent pin, the app UUID of the pin that created the reminder.

Parameters

	item	Item to inspect.
[out]	id	Originator id, UUID_INVALID on failure.

Returns

true on success, false for an invalid item type or a reminder without a parent pin.

timeline_get_private_data_source()

const char * timeline_get_private_data_source

(

Uuid *

parent_id

)

Get the name of a private (non-app) data source such as Weather or Calendar.

Parameters

parent_id

Parent id of an item.

Returns

Untranslated name (an i18n key), or NULL if parent_id is not a private data source.

timeline_init()

status_t timeline_init

(

TimelineNode **

timeline

)

Build the ordered pin list from the Pins database.

Expired pins are deleted from the database on the way.

Parameters

[out]

timeline

Head of the new list.

Returns

S_SUCCESS or an error from the Pins database.

timeline_invoke_action()

void timeline_invoke_action	(	const TimelineItem *	item,
		const TimelineItemAction *	action,
		const AttributeList *	attributes
	)

Invoke an action of a timeline item.

Local actions (opening an app or the parent pin, removing a watch pin, dismissing a local notification, ANCS actions) run on the watch; the others are sent to the phone, possibly over Bluetooth. The outcome is reported as a PebbleSysNotificationActionResult.

Parameters

item	Item the action belongs to.
action	Action to invoke.
attributes	Extra attributes sent with a remote action (e.g. a reply), may be NULL.

timeline_is_bulk_ancs_action_mode_enabled()

bool timeline_is_bulk_ancs_action_mode_enabled

(

void

)

Check whether bulk mode for ANCS actions is enabled.

Returns

true if enabled.

timeline_item_should_show()

bool timeline_item_should_show	(	CommonTimelineItemHeader *	header,
		TimelineIterDirection	direction
	)

Check whether an item shows up in a Timeline direction, ignoring all-day events.

Parameters

header	Header of the item.
direction	Timeline direction.

Returns

true if the item would show up now.

timeline_item_time_comparator()

int timeline_item_time_comparator	(	CommonTimelineItemHeader *	new_common,
		CommonTimelineItemHeader *	old_common,
		TimelineIterDirection	direction
	)

Compare items in Timeline order, ignoring all-day events.

Items shown in direction come first, then items are ordered by time.

Parameters

new_common	Header the result refers to.
old_common	Header compared against.
direction	Timeline direction.

Returns

Negative if new_common goes before old_common, positive if after, 0 if equal.

timeline_iter_copy_state()

void timeline_iter_copy_state	(	TimelineIterState *	dst_state,
		TimelineIterState *	src_state,
		Iterator *	dst_iter,
		Iterator *	src_iter
	)

Copy an iterator into another one.

The pin of dst_state is freed and left empty; refresh it with timeline_iter_refresh_pin().

Parameters

[out]	dst_state	Destination state.
	src_state	Source state.
[out]	dst_iter	Destination iterator.
	src_iter	Source iterator.

timeline_iter_deinit()

void timeline_iter_deinit	(	Iterator *	iter,
		TimelineIterState *	iter_state,
		TimelineNode **	head
	)

Free the pin list and the iterator's current pin.

Parameters

	iter	Iterator.
	iter_state	Iterator state.
[in,out]	head	Pin list; set to NULL.

timeline_iter_init()

status_t timeline_iter_init	(	Iterator *	iter,
		TimelineIterState *	iter_state,
		TimelineNode **	timeline,
		TimelineIterDirection	direction,
		time_t	timestamp
	)

Start iterating over the pin list.

On success iter_state holds the first pin. Advance with iter_next(), which reads the next pin into iter_state; iter_prev() goes the other way.

Parameters

[out]	iter	Iterator to initialize.
[out]	iter_state	Iterator state.
	timeline	Ordered pin list from timeline_init().
	direction	Iteration direction.
	timestamp	Time to start from.

Returns

S_SUCCESS, S_NO_MORE_ITEMS if no pin is shown in direction, or a Pins database error.

timeline_iter_refresh_pin()

void timeline_iter_refresh_pin

(

TimelineIterState *

iter_state

)

Reload the current pin from the Pins database.

Does not move the pin in the list if its timestamp changed. No-op if the pin no longer exists.

Parameters

iter_state

Iterator state.

timeline_iter_remove_node()

void timeline_iter_remove_node	(	TimelineNode **	timeline,
		TimelineNode *	node
	)

Remove a node from the pin list.

Parameters

[in,out]	timeline	Pin list.
	node	Node to remove and free.

timeline_iter_remove_node_with_id()

bool timeline_iter_remove_node_with_id	(	TimelineNode **	timeline,
		Uuid *	key
	)

Remove the first node with an id from the pin list.

Multi-day events have one node per day, so call repeatedly to remove all of them.

Parameters

[in,out]	timeline	Pin list.
	key	Pin id.

Returns

true if a node was found and removed.

timeline_nodes_equal()

bool timeline_nodes_equal	(	TimelineNode *	a,
		TimelineNode *	b
	)

Compare two nodes.

Parameters

a	First node, may be NULL.
b	Second node, may be NULL.

Returns

true if both have the same id and timestamp, or both are NULL.

timeline_remove()

bool timeline_remove

(

const Uuid *

id

)

Remove a pin through BlobDB, which emits a BlobDB delete event.

Parameters

id	Id of the pin.

Returns

true on success.