GestureInputManager

public final class GestureInputManager
extends Object

java.lang.Object
   ↳ com.google.wear.input.GestureInputManager

Manager for gesture inputs, allowing to subscribe to GestureEvent events and query different gesture related configurations.

To get an instance, use Sdk.getWearManager(Context,Class) (i.e. Sdk.getWearManager(context, GestureInputManager.class)).

This API requires the Sdk.FEATURE_WEAR_GESTURE_DETECTION featureto function. Otherwise, the APIs in this class will be no-op (i.e. will do nothing).

Functionalities

Subscribe for GestureEvents

The manager provides APIs to subscribe to GestureEvents. See the following APIs:

Get the device's support for gestures

The manager provides APIs to check what kind of gesture actions are supported by the device, and which of these supported actions are currently enabled. See the following APIs:

Manage hints for gesture input

The manager provides APIs that enable simplified and consistent hint-showing decisions. The client can use these APIs to decide whether or not a hint should be shown at a given moment. The manager also provides APIs for the client to mark events relevant for hint logic management (example: when a hint has been shown to the user, or when the user uses a gesture event).

The internal hint management logic differs from device to device, but is generally consistent across multiple applications throughout a given device. Thus, using these APIs allows the client's application to integrate smoothly with other applications on the user's device that support gesture input, which in turn provides a smoother gesture input experience to the user.

The hint management APIs are not mandatory to use, but the client is strongly recommended to use them so that they can easily provide meaningful gesture related hints to their users at reasonable times.

Experience Identifier

The term "Experience Identifier" is used across APIs relevant to manage hints.

The Experience Identifier is an identifier that should be chosen by the client to uniquely identify gesture input experience(s) in a given package for which hints should be managed together. For example:

  • Consider a screen with two buttons, both capable of processing gesture inputs. Let us assume that these buttons look and behave similarly, and that the client is confident that a user who has been hinted to use gesture input on the first button can easily understand the availability of gesture input on the second button. In this case, using the same Experience identifier for both buttons is recommended.
  • The same example as the one above applies even if the two UI elements are in different screens. As long as the client is confident that hints shown to one of these elements effectively applies to educate the user about gesture input usage on the other UI element, using the same Experience identifier for both buttons is recommended.

The Experience Identifier should be used consistently (without being changed) for a given set of gesture input experience(s). Changing this identifier will result in the hint management logic to be reset, which may result in hints being shown to the user more frequently than desired.

See the following APIs:

Example usage: 
GestureInputManager gestureInputManager;

 // Assume that this function handles showing hints for the UI element with a given
 // experience identifier, for a given action.
 boolean showHint(String experienceIdentifier, int action) {
   if (gestureInputManager.shouldShowHint(experienceIdentifier, action)) {
     drawHint(experienceIdentifier, action);
     gestureInputManager.notifyHintShown(experienceIdentifier, action);
   }
 }

 // Assume that this function processes GestureEvents that are handled by a UI element with
 // a given experience identifier.
 void onGestureEvent(GestureEvent event, String experienceIdentifier) {
   gestureInputManager.notifyGestureConsumed(event.getAction(), experienceIdentifier);
 }
.
Requires the Sdk#FEATURE_WEAR_GESTURE_DETECTION feature which can be detected using Sdk.hasApiFeature(String).

Requires the PackageManager.hasSystemFeature(String) feature which can be detected using PackageManager.hasSystemFeature(String).

See also:

Summary

Constants

String ACTION_GESTURE_INPUT_SETTINGS

Activity Action: On devices that support Sdk.FEATURE_WEAR_GESTURE_DETECTION, this can be used to launch an activity to allow users to configure gesture input.

int GESTURE_SUBSCRIBER_TYPE_LOCAL

Represents a subscription for the local device (e.g., the watch itself).

int GESTURE_SUBSCRIBER_TYPE_REMOTE

Represents a subscription for a remote device connected to the local device.

Fields

public static final int FLAG_HINT_STYLE_OVERLAY

Hint flag indicating that the hint is shown as an overlay that covers a space larger than the specific UI element being hinted.

Public methods

void addEnabledActionsChangeListener(Executor executor, Consumer<Set<Integer>> listener)

Adds a listener to listen to changes in the set of enabled actions.

void addGestureEventListener(int[] actions, View view, Executor executor, Consumer<GestureEvent> listener)

Adds a listener to GestureEvents that happen as the user interacts with the window hosting a given View.

void addGestureEventListener(ForegroundGestureSubscriptionParams params, Executor executor, Consumer<GestureEvent> listener)

Adds a listener to GestureEvents while the client is in the foreground (visible to the user), based on {code params}.

void addGestureEventListener(int[] actions, Window window, Executor executor, Consumer<GestureEvent> listener)

Adds a listener to GestureEvents that happen as the user interacts with a given Window.

int getGestureForAction(int action, int subscriberType)

Provides the gesture that corresponds to a given action for use on a subscriberType.

int getGestureForAction(int action)

Provides the gesture that corresponds to a given action for use on the local device.

int[] getSupportedActions()

Provides all the gesture actions supported for use by the local device.

int[] getSupportedActions(int subscriberType)

Provides all the gesture actions supported for use by a subscriberType.

boolean isActionEnabled(int action, int subscriberType)

Whether a given action is currently enabled for use by a subscriberType.

boolean isActionEnabled(int action)

Whether a given action is currently enabled for use by the local device.

boolean isActionSupported(int action)

Whether a given action is supported for use on the local device.

boolean isActionSupported(int action, int subscriberType)

Whether a given action is supported by the device.

void notifyGestureConsumed(String experienceIdentifier, int action)

Reports that a GestureEvent has been consumed by the user for the provided experienceIdentifier.

void notifyHintShown(String experienceIdentifier, int action)

Reports that a hint has been shown to the user to indicate that the given gesture action is available for the provided experienceIdentifier.

void removeEnabledActionsChangeListener(Consumer<Set<Integer>> listener)

Removes a listener that has previously been registered via addEnabledActionsChangeListener(Executor, Consumer).

void removeGestureEventListener(Consumer<GestureEvent> listener)

Removes a listener that has previously been registered via any of the addGestureEventListener(ForegroundGestureSubscriptionParams, Executor, Consumer) APIs.

boolean shouldShowHint(String experienceIdentifier, int action, int hintFlags)

Whether a hint should be shown to the user to indicate that the given gesture action is available for the provided experienceIdentifier.

boolean shouldShowHint(String experienceIdentifier, int action)

Same as shouldShowHint(String,int,int), with the hint flags omitted (set to 0).

Inherited methods

Constants

ACTION_GESTURE_INPUT_SETTINGS

Added in version 36.1 
public static final String ACTION_GESTURE_INPUT_SETTINGS

Activity Action: On devices that support Sdk.FEATURE_WEAR_GESTURE_DETECTION, this can be used to launch an activity to allow users to configure gesture input.

Input: nothing

Output: nothing

Constant Value: "com.google.wear.input.action.GESTURE_INPUT_SETTINGS"

GESTURE_SUBSCRIBER_TYPE_LOCAL

Added in API level 37 
public static final int GESTURE_SUBSCRIBER_TYPE_LOCAL

Represents a subscription for the local device (e.g., the watch itself).

Use this subscription type if you are using gesture events for controlling on-device features, like silencing a call while a Dialer app is not in the foreground.

Constant Value: 1 (0x00000001)

GESTURE_SUBSCRIBER_TYPE_REMOTE

Added in API level 37 
public static final int GESTURE_SUBSCRIBER_TYPE_REMOTE

Represents a subscription for a remote device connected to the local device.

Use this subscription type if the end client of the subscribed gesture events is a device that is not the gesture-producing device. For example: if an app on the watch subscribes to gesture events and sends the received events to a connected device, like a TV.

Constant Value: 2 (0x00000002)

Fields

FLAG_HINT_STYLE_OVERLAY

Added in API level 37 
public static final int FLAG_HINT_STYLE_OVERLAY

Hint flag indicating that the hint is shown as an overlay that covers a space larger than the specific UI element being hinted.

Public methods

addEnabledActionsChangeListener

Added in version 36.1 
public void addEnabledActionsChangeListener (Executor executor, 
                Consumer<Set<Integer>> listener)

Adds a listener to listen to changes in the set of enabled actions.

The listener will be invoked when the set of actions enabled on ANY subscriber type changes. The provided Set contains any action that is enabled on at least one subscriber type. To check the enabled state for a specific subscriber type, use isActionEnabled(int, int).

Parameters
executor Executor: the Executor on which the listener will be notified.
listener Consumer: a Consumer that will receive the new set of enabled actions. The Set provided to the listener cannot be modified.

addGestureEventListener

Added in version 36.1 
public void addGestureEventListener (int[] actions, 
                View view, 
                Executor executor, 
                Consumer<GestureEvent> listener)

Adds a listener to GestureEvents that happen as the user interacts with the window hosting a given View.

Similar to addGestureEventListener(int[],Window,Executor,Consumer), but the event listener follows the Window that the View is attached to. Gesture inputs will be delivered as long as the window to which the provided View is attached has focus (at the time of registration, or, if it gains focus after registration). The manager will handle tracking the window's focus and delivering GestureEvents only while the window hosting the View is focused. The GestureInputManager will also track if the View is attached to a different window, and associates the registration to the focus-state of the new window.

Note that, because an action needs to be enabled (isActionEnabled(int)) for the system to detect and emit any GestureEvent for it, a listener registered with this API will get no GestureEvent for an action if the action is not enabled.

If a listener that has already been added is used again with this API or with addGestureEventListener(int[],Window,Executor,Consumer), the previous registration will be overridden by the new registration. So, if you want to listen to events on different Windows/Views and/or receive events on different Executors, you should do multiple registrations with different listeners.

Parameters
actions int: an array of all the actions to subscribe to. This must be NOT empty, and all actions in this array must be supported (see isActionSupported(int)). Providing an empty array or a non-empty array that has an unsupported action will result in an IllegalArgumentException to be thrown.
Value is one of the following:
view View: the View on which received GestureEvents will be processed. Events are delivered to the listener only while the Window hosting this View has focus.
executor Executor: the Executor on which the listener will be notified.
listener Consumer: a Consumer that will receive the events.
Throws
IllegalArgumentException if the provided actions array is empty or includes an unsupported action.

addGestureEventListener

Added in API level 37 
public void addGestureEventListener (ForegroundGestureSubscriptionParams params, 
                Executor executor, 
                Consumer<GestureEvent> listener)

Adds a listener to GestureEvents while the client is in the foreground (visible to the user), based on {code params}.

If a listener that has already been added is used again with this API or any of the other foreground (View or Window based APIs), the previous registration will be overridden by the new registration. Each listener can only be registered once (subsequent registration on the same listener will override the previous one).

Parameters
params ForegroundGestureSubscriptionParams: parameters for the subscription.
executor Executor: the Executor on which the listener will be notified.
listener Consumer: a Consumer that will receive the events.

addGestureEventListener

Added in version 36.1 
public void addGestureEventListener (int[] actions, 
                Window window, 
                Executor executor, 
                Consumer<GestureEvent> listener)

Adds a listener to GestureEvents that happen as the user interacts with a given Window. The given Window needs to have a decor view (i.e. Window.peekDecorView() should not be null) by the time this method is called.

The gesture inputs are delivered as GestureEvents as long as the provided Window has focus (at the time of registration, or, if it gains focus after registration). The GestureInputManager will handle tracking the window's focus and delivering GestureEvents only while the window is focused.

Note that, because an action needs to be enabled (isActionEnabled(int)) for the system to detect and emit any GestureEvent for it, a listener registered with this API will get no GestureEvent for an action if the action is not enabled.

If a listener that has already been added is used again with this API or with addGestureEventListener(int[],View,Executor,Consumer), the previous registration will be overridden by the new registration. So, if you want to listen to events on different Windows/Views and/or receive events on different Executors, you should do multiple registrations with different listeners.

Parameters
actions int: an array of all the actions to subscribe to. This must be NOT empty, and all actions in this array must be supported (see isActionSupported(int)). Providing an empty array or a non-empty array that has an unsupported action will result in an IllegalArgumentException to be thrown.
Value is one of the following:
window Window: the Window on which received GestureEvents will be processed. This window should have a View attached (i.e. Window.peekDecorView() should not be null). Otherwise, the method will throw an IllegalArgumentException. Events are delivered to the listener only while this window has focus.
executor Executor: the Executor on which the listener will be notified.
listener Consumer: a Consumer that will receive the events.
Throws
IllegalArgumentException if the provided actions array is empty or includes an unsupported action, or, if the provided Window does not have a decor view.

getGestureForAction

Added in API level 37 
public int getGestureForAction (int action, 
                int subscriberType)

Provides the gesture that corresponds to a given action for use on a subscriberType.

Parameters
action int: the gesture action for which the corresponding gesture is being queried.
Value is one of the following:
subscriberType int: the type of subscription where the gesture events will be used.
Value is one of the following:
Returns
int the gesture that corresponds to the given action. If the provided action is invalid, or the action is not supported by the devices matching the filter, returns GestureEvent.GESTURE_UNKNOWN.
Value is one of the following:

getGestureForAction

Added in version 36.1 
public int getGestureForAction (int action)

Provides the gesture that corresponds to a given action for use on the local device.

Parameters
action int: Value is one of the following:
Returns
int Value is one of the following:

getSupportedActions

Added in version 36.1 
public int[] getSupportedActions ()

Provides all the gesture actions supported for use by the local device.

Returns
int[] Value is one of the following:

getSupportedActions

Added in API level 37 
public int[] getSupportedActions (int subscriberType)

Provides all the gesture actions supported for use by a subscriberType.

The supported actions for a device are fixed on a given device build and do not change.

Parameters
subscriberType int: the type of subscription where the gesture events will be used.
Value is one of the following:
Returns
int[] an array of all supported gesture actions.
Value is one of the following:

isActionEnabled

Added in API level 37 
public boolean isActionEnabled (int action, 
                int subscriberType)

Whether a given action is currently enabled for use by a subscriberType.

An action is considered enabled if it is supported and gesture detection is currently available for it (that is, the system will detect GestureEvents for that action, and these events will be emitted to listeners registered through the addGestureEventListener APIs).

Whether an action is enabled could be affected by user preference. It could also be impacted by internal system states.

If an action is not enabled, no GestureEvent will be emitted for the action. Thus, A GestureEvent listener registered through the addGestureEventListener APIs can receive GestureEvents for an action only if that action is enabled.

A listener will start receiving GestureEvents for the action if the action gets enabled after the listener was added (as long the listener has not yet been removed). Similarly, if an action gets disabled after a listener was added for it, the listener will not get any GestureEvent until the action is enabled again.

Use the addEnabledActionsChangeListener(Executor, Consumer) API to register listeners that receive changes to the set of enabled actions.

Parameters
action int: the action to be checked if it is enabled.
Value is one of the following:
subscriberType int: the type of subscription where the gesture events will be used.
Value is one of the following:
Returns
boolean true if the given action is enabled. false otherwise.

isActionEnabled

Added in version 36.1 
public boolean isActionEnabled (int action)

Whether a given action is currently enabled for use by the local device.

Parameters
action int: Value is one of the following:
Returns
boolean

isActionSupported

Added in version 36.1 
public boolean isActionSupported (int action)

Whether a given action is supported for use on the local device.

Parameters
action int: Value is one of the following:
Returns
boolean

isActionSupported

Added in API level 37 
public boolean isActionSupported (int action, 
                int subscriberType)

Whether a given action is supported by the device.

Parameters
action int: the action to be checked if it is supported by the device.
Value is one of the following:
subscriberType int: the type of subscription where the gesture events will be used.
Value is one of the following:
Returns
boolean true if the given action is supported. false otherwise.

notifyGestureConsumed

Added in version 36.1 
public void notifyGestureConsumed (String experienceIdentifier, 
                int action)

Reports that a GestureEvent has been consumed by the user for the provided experienceIdentifier.

This API should be consistently used by the client to report consumed gesture events so that the manager can provide a consistent and reasonable decision on whether to shown hints to the user in the future (shouldShowHint(String,int)).

Parameters
experienceIdentifier String: the experience identifier for which a gesture has been consumed. Refer to the top-level documentation in this class to learn more about Experience Identifiers.
action int: the action of the consumed gesture event (GestureEvent.getAction()).
Value is one of the following:

notifyHintShown

Added in version 36.1 
public void notifyHintShown (String experienceIdentifier, 
                int action)

Reports that a hint has been shown to the user to indicate that the given gesture action is available for the provided experienceIdentifier.

This API should be consistently used by the client to report when hints are shown so that the manager can provide a consistent and reasonable decision on whether to shown hints to the user in the future (shouldShowHint(String,int)).

Parameters
experienceIdentifier String: the experience identifier for which hint has been shown. Refer to the top-level documentation in this class to learn more about Experience Identifiers.
action int: the gesture action for which hint has been shown.
Value is one of the following:

removeEnabledActionsChangeListener

Added in version 36.1 
public void removeEnabledActionsChangeListener (Consumer<Set<Integer>> listener)

Removes a listener that has previously been registered via addEnabledActionsChangeListener(Executor, Consumer). If the provided listener was never registered or has already been removed, this method will return without doing anything.

Parameters
listener Consumer: the Consumer to remove.

removeGestureEventListener

Added in version 36.1 
public void removeGestureEventListener (Consumer<GestureEvent> listener)

Removes a listener that has previously been registered via any of the addGestureEventListener(ForegroundGestureSubscriptionParams, Executor, Consumer) APIs. If the provided listener was never registered or has already been removed, this method will return without doing anything.

Parameters
listener Consumer: the Consumer to remove.

shouldShowHint

Added in API level 37 
public boolean shouldShowHint (String experienceIdentifier, 
                int action, 
                int hintFlags)

Whether a hint should be shown to the user to indicate that the given gesture action is available for the provided experienceIdentifier.

This API should be used each time when a gesture experience is displayed to the user. For example, if your gesture experience is in a View, you should use this API when the View becomes visible. If the experience is in an Activity, you should call it when the Activity is resumed. If the API returns true, you should hint the user (in a way that makes sense for and is cohesive with the overall UX) about the availability and usage of the gesture experience.

Parameters
experienceIdentifier String: the experience identifier to check whether a hint should be shown for. Refer to the top-level documentation in this class to learn more about Experience Identifiers.
action int: the gesture action to check whether a hint should be shown for.
Value is one of the following:
hintFlags int: a bitmask of flags providing additional information about the hint that is being shown. For example, this can indicate if the hint is an overlay. See FLAG_HINT_ values.
Value is either 0 or
Returns
boolean true if the manager suggests showing a hint for the provided experienceIdentifier and action; false otherwise.

shouldShowHint

Added in version 36.1 
public boolean shouldShowHint (String experienceIdentifier, 
                int action)

Same as shouldShowHint(String,int,int), with the hint flags omitted (set to 0).

Parameters
experienceIdentifier String: the experience identifier to check whether a hint should be shown for. Refer to the top-level documentation in this class to learn more about Experience Identifiers.
action int: the gesture action to check whether a hint should be shown for.
Value is one of the following:
Returns
boolean true if the manager suggests showing a hint for the provided experienceIdentifier and action; false otherwise.