Touch

Touchscreen input: raw touch and gesture events, navigation gating and injection. More...

Modules
	Touch navigation
	Enabling and disabling system touch navigation.
	Touch interaction session
	Interaction session gating raw touch navigation.

Data Structures
struct	GestureEvent
	Gesture event data, carried in PebbleGestureEvent. More...
struct	TouchWakeGateResult
	Outcome of the session gate decision made on a Touchdown. More...

Typedefs
typedef void(*	TouchEventHandler) (const TouchEvent *event, void *context)
	Touch event callback.

Enumerations
enum	GestureEventType { GestureEvent_Tap , GestureEvent_DoubleTap , GestureEvent_Palm }
	Gesture event type. More...
enum	TouchState { TouchState_FingerUp , TouchState_FingerDown }
	Finger state reported by the touch driver. More...
enum	TouchGesture { TouchGesture_Tap , TouchGesture_DoubleTap , TouchGesture_Palm }
	Gesture reported by the touch driver. More...
enum	TouchInjectPhase { TouchInjectPhase_Begin , TouchInjectPhase_Move , TouchInjectPhase_End }
	Phase of an injected gesture. More...

Functions
void	touch_init (void)
	Initialize the service and register the touch and gesture event types.
void	touch_set_backlight_enabled (bool enabled)
	Enable or disable the kernel touch subscription used by the touch backlight feature.
void	touch_set_system_hold (bool held)
	Hold the sensor powered for system touch navigation.
bool	touch_nav_enabled (void)
	Check whether system touch navigation is enabled.
void	touch_set_nav_enabled (bool enabled)
	Set the system navigation gate.
bool	touch_app_nav_active (void)
	Check whether the app navigation dispatcher is installed for the running app.
void	touch_set_app_nav_active (bool active)
	Mark whether the app navigation dispatcher is installed.
bool	touch_has_app_subscribers (void)
	Check for explicit raw touch subscriptions.
void	touch_service_set_globally_enabled (bool enabled)
	Globally enable or disable touch.
bool	touch_service_is_globally_enabled (void)
	Get the global touch enable flag.
void	touch_handle_update (TouchState touch_state, int16_t x, int16_t y)
	Pass a touch sample to the service.
void	touch_handle_gesture (TouchGesture gesture, int16_t x, int16_t y)
	Pass a gesture to the service.
void	touch_reset (void)
	Reset the touch state.
void	touch_release_active (void)
	End an in-progress touch with a synthetic Liftoff.
void	touch_wake_gate_stamp (TouchEvent *event, TouchWakeGateResult gate)
	Stamp non_navigational onto a touch event.
void	touch_set_rotated (bool rotated)
	Set whether the display is rotated by 180 degrees (left-hand mode).
bool	touch_handle_injected_update (TouchInjectPhase phase, int16_t x, int16_t y)
	Inject a synthetic touch sample.
bool	touch_injection_is_available (void)
	Check whether a new injected gesture would be accepted.

Detailed Description

Touchscreen input: raw touch and gesture events, navigation gating and injection.

The touch driver reports samples with touch_handle_update() and gestures with touch_handle_gesture(). The service turns them into PEBBLE_TOUCH_EVENT (Touchdown, PositionUpdate, Liftoff) and PEBBLE_GESTURE_EVENT events, mirroring coordinates in left-hand mode. The sensor is powered while anything holds it: event service subscribers, the touch backlight feature or the system navigation hold, unless touch is globally disabled.

---

Data Structure Documentation

GestureEvent

struct GestureEvent

Gesture event data, carried in PebbleGestureEvent.

Data Fields
GestureEventType	type: 8	Gesture.
int16_t	x	X coordinate in pixels.
int16_t	y	Y coordinate in pixels.

TouchWakeGateResult

struct TouchWakeGateResult

Outcome of the session gate decision made on a Touchdown.

Data Fields
bool	latch	true when the touch must not drive navigation: the interaction session (touch_session_is_active()) was inactive at Touchdown, i.e. unarmed contact on the idle watchface.

Typedef Documentation

TouchEventHandler

typedef void(* TouchEventHandler) (const TouchEvent *event, void *context)

Touch event callback.

Parameters

event	Touch event.
context	Callback context.

Enumeration Type Documentation

GestureEventType

enum GestureEventType

Gesture event type.

Enumerator
GestureEvent_Tap	Single tap.
GestureEvent_DoubleTap	Double tap.
GestureEvent_Palm

TouchGesture

enum TouchGesture

Gesture reported by the touch driver.

Enumerator
TouchGesture_Tap	Single tap.
TouchGesture_DoubleTap	Double tap.
TouchGesture_Palm

TouchInjectPhase

enum TouchInjectPhase

Phase of an injected gesture.

Stated explicitly rather than inferred from the finger state: a mid-path sample and a fresh touchdown are both "finger down", so a gesture that lost the sensor (a reset, or touch switched off) could otherwise have its next sample taken as the start of a new one.

Enumerator
TouchInjectPhase_Begin	Touchdown, claiming the sensor.
TouchInjectPhase_Move	Position update; requires the gesture to still own the sensor.
TouchInjectPhase_End	Liftoff, releasing the sensor.

TouchState

enum TouchState

Finger state reported by the touch driver.

Enumerator
TouchState_FingerUp	No finger on the screen.
TouchState_FingerDown	A finger is on the screen.

Function Documentation

touch_app_nav_active()

bool touch_app_nav_active

(

void

)

Check whether the app navigation dispatcher is installed for the running app.

True with system navigation active, or for an opted-in third-party app under the master pref. Cleared as well when the app's touch subscription is torn down, so a dead app cannot leave it set. Feeds the dispatch gate and touch-driven backlight behavior.

Returns

true while the app navigation dispatcher is installed.

touch_handle_gesture()

void touch_handle_gesture	(	TouchGesture	gesture,
		int16_t	x,
		int16_t	y
	)

Pass a gesture to the service.

Called by the touch driver. Dropped while touch is globally disabled or an injected gesture owns the sensor.

Parameters

gesture	Detected gesture.
x	X coordinate in pixels, before left-hand mode mirroring.
y	Y coordinate in pixels, before left-hand mode mirroring.

touch_handle_injected_update()

bool touch_handle_injected_update	(	TouchInjectPhase	phase,
		int16_t	x,
		int16_t	y
	)

Inject a synthetic touch sample.

Intended for automated input (remote input endpoint, console commands), not for drivers. Coordinates are the ones the UI observes: left-hand mode mirroring is not applied.

A Begin arms the interaction session as a button press does, so contact on the idle watchface is not dropped as unarmed. The sensor belongs to whoever puts a finger down first: a Begin is refused while a physical finger is down, and physical samples are ignored until the injected gesture ends. A Move or End is refused unless the gesture still owns the sensor, so the caller learns it was interrupted.

// Swipe up through the middle of the screen.
if (touch_handle_injected_update(TouchInjectPhase_Begin, 100, 180)) {
  bool ok = touch_handle_injected_update(TouchInjectPhase_Move, 100, 120) &&
            touch_handle_injected_update(TouchInjectPhase_Move, 100, 60);
  if (ok) {
    touch_handle_injected_update(TouchInjectPhase_End, 100, 60);
  }
}

Parameters

phase	Gesture phase.
x	X coordinate in pixels.
y	Y coordinate in pixels.

Returns

false if the sample was dropped.

touch_handle_update()

void touch_handle_update	(	TouchState	touch_state,
		int16_t	x,
		int16_t	y
	)

Pass a touch sample to the service.

Called by the touch driver. Emits Touchdown or Liftoff on state changes and PositionUpdate when a down finger moves. Dropped while touch is globally disabled or an injected gesture owns the sensor.

Parameters

touch_state	Whether the screen is touched.
x	X coordinate in pixels, before left-hand mode mirroring.
y	Y coordinate in pixels, before left-hand mode mirroring.

touch_has_app_subscribers()

bool touch_has_app_subscribers

(

void

)

Check for explicit raw touch subscriptions.

Only touch_service_subscribe() subscriptions count: navigation dispatchers, the backlight subscription and the system hold do not.

Returns

true if at least one task holds a raw touch subscription.

touch_init()

void touch_init

(

void

)

Initialize the service and register the touch and gesture event types.

touch_injection_is_available()

bool touch_injection_is_available

(

void

)

Check whether a new injected gesture would be accepted.

Returns

false if touch is globally disabled or a physical finger owns the sensor.

touch_nav_enabled()

bool touch_nav_enabled

(

void

)

Check whether system touch navigation is enabled.

Off by default; the shell sets it with touch_set_nav_enabled() from the master "Touch" pref and the "Touch Navigation" sub-pref.

Returns

true when system touch navigation is effectively enabled.

touch_release_active()

void touch_release_active

(

void

)

End an in-progress touch with a synthetic Liftoff.

Uses the last known coordinates so backlight hold counters and gesture state unwind when touch is torn down with a finger on the screen. Does nothing if no finger is down.

touch_reset()

void touch_reset

(

void

)

Reset the touch state.

Forgets the finger state and last position and ends any injected gesture, without emitting events.

touch_service_is_globally_enabled()

bool touch_service_is_globally_enabled

(

void

)

Get the global touch enable flag.

Returns

true if touch is globally enabled.

touch_service_set_globally_enabled()

void touch_service_set_globally_enabled

(

bool

enabled

)

Globally enable or disable touch.

When disabled, the sensor is powered down even if subscribers exist, driver samples and gestures are dropped, touch_service_is_enabled() returns false to apps, and an in-progress touch gets a synthetic Liftoff. Subscribers stay subscribed and receive events again when re-enabled. Backs a user setting persisted by the shell, which calls this on boot.

Parameters

enabled

true to enable touch.

touch_set_app_nav_active()

void touch_set_app_nav_active

(

bool

active

)

Mark whether the app navigation dispatcher is installed.

Parameters

active

true when installed.

touch_set_backlight_enabled()

void touch_set_backlight_enabled

(

bool

enabled

)

Enable or disable the kernel touch subscription used by the touch backlight feature.

When disabled, the sensor is only powered while other holders remain.

Parameters

enabled

true to hold the sensor for the backlight feature.

touch_set_nav_enabled()

void touch_set_nav_enabled

(

bool

enabled

)

Set the system navigation gate.

Driven by the shell pref system when the effective (master and sub-pref) state changes.

Parameters

enabled

true to enable system touch navigation.

touch_set_rotated()

void touch_set_rotated

(

bool

rotated

)

Set whether the display is rotated by 180 degrees (left-hand mode).

When rotated, driver coordinates are mirrored to match the rotated framebuffer before being dispatched.

Parameters

rotated

true when rotated.

touch_set_system_hold()

void touch_set_system_hold

(

bool

held

)

Hold the sensor powered for system touch navigation.

Unlike the backlight subscription, this holds the sensor directly, without an event service subscription. Taken when the master navigation pref turns on, released when it turns off.

Parameters

held	true to take the hold, false to release it.

touch_wake_gate_stamp()

void touch_wake_gate_stamp	(	TouchEvent *	event,
		TouchWakeGateResult	gate
	)

Stamp non_navigational onto a touch event.

Latches the Touchdown decision across the whole gesture: gate is only consulted on a Touchdown; PositionUpdate and Liftoff carry the latched value. KernelMain only.

Parameters

[in,out]	event	Touch event to stamp.
	gate	Gate decision for a Touchdown.