feat(wear): add One-Handed Gestures demo snippet by ithinkihaveacat · Pull Request #1001 · android/snippets

ithinkihaveacat · 2026-07-30T12:19:38Z

Summary

This PR adds standalone, self-contained documentation snippets for Wear OS One-Handed Gestures (Wear OS 7+, API 37+) using Wear Compose Material 3. It demonstrates scrollable container gestures and interactive button click gestures (Double Pinch and Wrist Turn).

Important

Subproject Addition (:wear:snapshot): This PR introduces a new subproject :wear:snapshot (wear/snapshot/) specifically to house the gestures snippet.

Why :wear:snapshot? Building this snippet currently requires 1.7.0-SNAPSHOT. Creating a dedicated subproject isolates 1.7.0-SNAPSHOT from the main :wear module, protecting the rest of the :wear codebase from potential snapshot build breakages.
Expected Lifespan: This snapshot requirement is expected to go away in the first 1.7.0 beta release, at which point OneHandedGestures.kt will be merged back into the main :wear module.

Implementation

Isolated Subproject (:wear:snapshot):
- Registered :wear:snapshot in settings.gradle.kts.
- Created wear/snapshot/build.gradle.kts enforcing 1.7.0-SNAPSHOT for wear-compose-material3 and compose-foundation.
- Added OneHandedGestures.kt under wear/snapshot/src/main/java/com/example/wear/snippets/m3/gestures/OneHandedGestures.kt.
Main :wear Module:
- Uses standard stable catalog dependencies (libs.wear.compose.material3).

How to Test

Build :wear:snapshot subproject locally:

./gradlew :wear:snapshot:compileDebugKotlin

Run full project build & format checks:
```
./gradlew build
./gradlew spotlessCheck
```

Add self-contained Wear OS One-Handed Gestures demo snippet to com.example.wear.snippets.m3.gestures. Gate SNAPSHOT dependencies (compose-material3 and foundation) on isUsingSnapshot in wear/build.gradle.kts to avoid modifying shared catalog versions in libs.versions.toml. Update CI workflows to pass -PsnapshotVersion=1.7.0-SNAPSHOT during PR validation builds.

Move the KDoc note about -PsnapshotVersion=1.7.0-SNAPSHOT below the package declaration so that ktlint does not report multiple header blocks above package.

Pin third-party GitHub Actions to immutable commit SHAs and define explicit job-level permissions blocks in build.yml and apply_spotless.yml to remediate mandatory Zizmor security analysis findings.

Namespace Wear snapshot gating property to wearSnapshotVersion so that passing -PwearSnapshotVersion=1.7.0-SNAPSHOT in CI workflows does not trigger snapshot builds in the xr module.

Rename wearSnapshotVersion to wearComposeOverride to match the wearCompose prefix convention used in libs.versions.toml.

Add concise 5-6 line snippet examples for scrollable and button one-handed gestures so they can be included cleanly in developer documentation without embedding an entire screen.

Include compose.foundation in the isUsingSnapshot override block so that -PwearComposeOverride=1.7.0-SNAPSHOT also updates Wear Compose Foundation to 1.7.0-SNAPSHOT during CI builds.

Remove priority setting from ButtonGestureSnippet so the initial interactive button example in documentation is minimal and simple.

Update ButtonGestureSnippet to show a clean Button composable with Modifier.oneHandedGesture without unnecessary conditional modifiers or indicator state boilerplate.

Declare remember { MutableInteractionSource() } inside ButtonGestureSnippet so the documentation example is self-contained and runnable, and add an inline comment explaining why interactionSource is shared.

Make ScrollGestureSnippet self-contained and runnable without priority, and add highlight region tags around .oneHandedGesture in both snippets.

Remove nested highlight region tags from ButtonGestureSnippet and ScrollGestureSnippet.

Add self-contained ButtonGestureHintSnippet demonstrating how to wrap a button with OneHandedGestureClickIndicator and call showIndicator inside onGestureAvailable.

Add self-contained ScrollGestureHintSnippet demonstrating how to display OneHandedGestureScrollIndicator within ScreenScaffold.

Address review feedback by aligning OneHandedGestureScreen and ScrollGestureHintSnippet with official AndroidX samples: - Wire onGestureAvailable to trigger indicatorState.showIndicator() on all gesture modifiers so animated hints display correctly. - Remove redundant onVisibilityChanged modifier from always-visible button in OneHandedGestureScreen. - Remove unused interactionSource from scrollable list containers.

Address review feedback across OneHandedGestures.kt snippets: - Use lowercase verb phrase strings for onGestureLabel to prevent redundant screen reader accessibility prompts. - Key OneHandedGestureScrollIndicatorState remember blocks to their respective gesture configurations to avoid stale state.

Restore onVisibilityChanged check on interactive button inside OneHandedGestureScreen so off-screen buttons do not intercept one-handed gestures over scrollable list containers.

Specify priority = OneHandedGesturePriority.Scrollable in list gesture configurations across ScrollGestureSnippet and ScrollGestureHintSnippet so clickable child items take precedence over list scrolling.

Align OneHandedGestureScreen with official Wear Compose M3 samples by moving the interactive Play/Pause button into EdgeButton inside ScreenScaffold, conditionally enabling gesture capture only when the list cannot scroll forward. Remove unused sample tags and snippets to match documentation usage.

Align Wear Compose M3 one-handed gesture samples with official conventions: - Make ButtonGestureSnippet self-contained without external parameters. - Use lowercase verb phrases ("pause"/"play", "scroll") for gesture accessibility labels across snippets and app demo screen. - Move buttonInteractionSource to outer screen scope in demo screen. - Use plain Text items instead of cards in transforming list demo.

Use a standard Button in ButtonGestureHintSnippet and remove unused imports from OneHandedGestures.kt per review feedback.

Isolate OneHandedGestures.kt compilation behind property wearGesturesVersionOverride so snapshot dependencies are used strictly when enabled and standard builds compile cleanly. Update CI workflows and KDoc documentation to use new flag.

snippet-bot · 2026-08-10T17:49:01Z

Here is the summary of changes.

You are about to add 3 region tags.

wear/snapshot/src/main/java/com/example/wear/snippets/m3/gestures/OneHandedGestures.kt:162, tag android_wear_one_handed_gesture_button
wear/snapshot/src/main/java/com/example/wear/snippets/m3/gestures/OneHandedGestures.kt:191, tag android_wear_one_handed_gesture_button_hint
wear/snapshot/src/main/java/com/example/wear/snippets/m3/gestures/OneHandedGestures.kt:227, tag android_wear_one_handed_gesture_scroll_hint

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

Refresh this comment

kkuan2011 · 2026-08-10T18:13:50Z

Hi Michael! Since this module isn't needed long-term, is it possible to keep this code on a branch in the snippets repo? (and point to that branch from the DAC page)?
An example from Compose: #936

kul3r4 · 2026-08-10T19:12:51Z

@kkuan2011 we intend to update to beta on the 12th upon API availability, as for now we just need to push to propagate the changes so that those will be available on DAC

ithinkihaveacat added 30 commits July 30, 2026 13:09

fix(wear): move comment after package

21f50ef

Move the KDoc note about -PsnapshotVersion=1.7.0-SNAPSHOT below the package declaration so that ktlint does not report multiple header blocks above package.

ci: pin GitHub actions to SHAs and add permissions

8e0bcda

Pin third-party GitHub Actions to immutable commit SHAs and define explicit job-level permissions blocks in build.yml and apply_spotless.yml to remediate mandatory Zizmor security analysis findings.

fix(wear): isolate snapshot flag

eaa9039

Namespace Wear snapshot gating property to wearSnapshotVersion so that passing -PwearSnapshotVersion=1.7.0-SNAPSHOT in CI workflows does not trigger snapshot builds in the xr module.

refactor(wear): rename snapshot property

2ecc5e2

Rename wearSnapshotVersion to wearComposeOverride to match the wearCompose prefix convention used in libs.versions.toml.

feat(wear): add 6-line snippet regions for DAC

91bd36e

Add concise 5-6 line snippet examples for scrollable and button one-handed gestures so they can be included cleanly in developer documentation without embedding an entire screen.

fix(wear): override compose-foundation when using snapshot

24f87b9

Include compose.foundation in the isUsingSnapshot override block so that -PwearComposeOverride=1.7.0-SNAPSHOT also updates Wear Compose Foundation to 1.7.0-SNAPSHOT during CI builds.

docs(wear): simplify button gesture snippet

2b5a8ae

Remove priority setting from ButtonGestureSnippet so the initial interactive button example in documentation is minimal and simple.

docs(wear): improve button gesture snippet

490765d

Update ButtonGestureSnippet to show a clean Button composable with Modifier.oneHandedGesture without unnecessary conditional modifiers or indicator state boilerplate.

docs(wear): make button snippet runnable

eeb56f5

Declare remember { MutableInteractionSource() } inside ButtonGestureSnippet so the documentation example is self-contained and runnable, and add an inline comment explaining why interactionSource is shared.

docs(wear): enhance scroll snippet and highlight

daf52ca

Make ScrollGestureSnippet self-contained and runnable without priority, and add highlight region tags around .oneHandedGesture in both snippets.

docs(wear): remove highlight region tags

ec45263

Remove nested highlight region tags from ButtonGestureSnippet and ScrollGestureSnippet.

docs(wear): add button gesture hint snippet

c7e8b56

Add self-contained ButtonGestureHintSnippet demonstrating how to wrap a button with OneHandedGestureClickIndicator and call showIndicator inside onGestureAvailable.

docs(wear): add scroll gesture hint snippet

c6ae585

Add self-contained ScrollGestureHintSnippet demonstrating how to display OneHandedGestureScrollIndicator within ScreenScaffold.

docs(wear): check button visibility in list

4414014

Restore onVisibilityChanged check on interactive button inside OneHandedGestureScreen so off-screen buttons do not intercept one-handed gestures over scrollable list containers.

docs(wear): specify scrollable priority on lists

8b0b24b

Specify priority = OneHandedGesturePriority.Scrollable in list gesture configurations across ScrollGestureSnippet and ScrollGestureHintSnippet so clickable child items take precedence over list scrolling.

Merge branch 'main' into wear-m3-one-handed-gestures

27629b3

docs(wear): refactor hint snippet button

a1248cc

Use a standard Button in ButtonGestureHintSnippet and remove unused imports from OneHandedGestures.kt per review feedback.

Merge branch 'main' into wear-m3-one-handed-gestures

c1c8b07

build(wear): isolate gestures snapshot flag

2e3c3c5

Isolate OneHandedGestures.kt compilation behind property wearGesturesVersionOverride so snapshot dependencies are used strictly when enabled and standard builds compile cleanly. Update CI workflows and KDoc documentation to use new flag.

ci: revert action sha pinning in workflows

24b4c16

ci: document gestures snapshot flag

feccbf2

refactor(wear): inline snapshot dependencies

d7ff5cd

feat(wear): extract gestures to wear:snapshot

b237c47

docs(wear): note snapshot dependency removal

33270d7

feat(wear): update scroll helper to scrollDown

f994743

refactor(wear): revert MainActivity test edit

009618d

ithinkihaveacat marked this pull request as ready for review August 10, 2026 17:48

ithinkihaveacat requested review from a team as code owners August 10, 2026 17:48

ithinkihaveacat enabled auto-merge (squash) August 10, 2026 17:54

kul3r4 approved these changes Aug 10, 2026

View reviewed changes

ithinkihaveacat changed the base branch from main to wear-m3-one-handed-gestures August 10, 2026 19:50

ithinkihaveacat merged commit 982f669 into android:wear-m3-one-handed-gestures Aug 10, 2026
10 checks passed

Navigation Menu

Uh oh!

feat(wear): add One-Handed Gestures demo snippet - #1001

feat(wear): add One-Handed Gestures demo snippet#1001
ithinkihaveacat merged 31 commits into
android:wear-m3-one-handed-gesturesfrom
ithinkihaveacat:wear-m3-one-handed-gestures

ithinkihaveacat commented Jul 30, 2026 •

edited

Loading

Uh oh!

snippet-bot Bot commented Aug 10, 2026

Uh oh!

kkuan2011 commented Aug 10, 2026

Uh oh!

kul3r4 commented Aug 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

ithinkihaveacat commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Implementation

How to Test

Uh oh!

snippet-bot Bot commented Aug 10, 2026

Uh oh!

kkuan2011 commented Aug 10, 2026

Uh oh!

kul3r4 commented Aug 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ithinkihaveacat commented Jul 30, 2026 •

edited

Loading