Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
87f0db2
feat(home): add Copy report and Report a bug
heykay-47 Oct 29, 2026
98655de
feat(home): add a Try button to each gesture
heykay-47 Oct 29, 2026
1f041d1
feat(tile): add a Snap Key Quick Settings tile
heykay-47 Oct 29, 2026
b030ce0
feat(home): back up and restore settings
heykay-47 Oct 29, 2026
754b916
Merge pull request #48 from heykay-47/v1.2/bug-report
heykay-47 Oct 29, 2026
0d9bfef
chore(release): prepare v1.2.0
heykay-47 Oct 29, 2026
f319b4e
Merge pull request #49 from heykay-47/v1.2/try-action
heykay-47 Oct 29, 2026
c0e6877
Merge pull request #50 from heykay-47/v1.2/qs-tile
heykay-47 Oct 29, 2026
9fa28b4
Merge pull request #51 from heykay-47/v1.2/backup
heykay-47 Oct 29, 2026
035b0fb
Merge pull request #52 from heykay-47/v1.2/release-prep
heykay-47 Oct 29, 2026
554ef29
docs(privacy): disclose key events and window changes the accessibili…
heykay-47 Oct 30, 2026
891a9e8
fix(privacy): correct accessibility disclosures
heykay-47 Oct 30, 2026
1c7882b
test(learning): characterize generic StylusModule false positive
heykay-47 Oct 30, 2026
3d82d2d
Merge remote-tracking branch 'origin/v1.2/integration' into v1.2/teac…
heykay-47 Oct 30, 2026
82d979a
Merge pull request #53 from heykay-47/v1.2/a11y-disclosure
heykay-47 Oct 30, 2026
4d6bd60
fix(learning): require different-key proof before saving
heykay-47 Oct 30, 2026
cc19f93
fix: preserve teaching state through cancellation and save failures
heykay-47 Oct 30, 2026
97e2d81
fix(teaching): preserve context-free candidate edge phase
heykay-47 Oct 30, 2026
ee29d01
fix(teaching): preserve log phase across stale delivery
heykay-47 Oct 30, 2026
18126a2
Merge pull request #65 from heykay-47/v1.2/teach-validation
heykay-47 Oct 31, 2026
c892ec3
fix(home): put the Details report actions on one row
heykay-47 Oct 31, 2026
9fbcb68
docs(release): add safer teaching and the disclosure to the 1.2.0 notes
heykay-47 Oct 31, 2026
3bb454a
Merge pull request #66 from heykay-47/v1.2/compact-details
heykay-47 Oct 31, 2026
d984b61
Merge pull request #67 from heykay-47/v1.2/release-notes
heykay-47 Oct 31, 2026
d9ea85b
Merge branch 'main' into v1.2/integration
heykay-47 Oct 31, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ Tap the lock next to a gesture to run it only when your phone is unlocked.

On the home screen you can pause the key in chosen apps, such as the camera, and hide confirmation pop-ups. Errors still show.

Tap ▶ next to a gesture to try its action without pressing the key. Turn the mapping on or off from the **Snap Key** Quick Settings tile. Back up your settings, including the learned key, to a file and restore them after a reinstall. **Details** on the status card can copy a bug report or open a prefilled bug form.

The app follows Material 3 with dynamic colour and a System, Light, or Dark theme. It declares no internet permission.

# Requirements
Expand Down
11 changes: 11 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,17 @@ The F-Droid submission will request the same developer-signed APK as GitHub Rele
- [x] **Release v1.0.15 with release notes.** The first release built for F-Droid. Each release since then passes the reproducibility check.
- [ ] **Submit to F-Droid.** Open a merge request in [fdroiddata](https://gitlab.com/fdroid/fdroiddata) with the build recipe. Review can take days or weeks.

## Delivered in v1.2.0

Quality-of-life additions for everyday use. Behaviour on other firmware may differ.

- [x] **Try a gesture.** Tap ▶ next to an assigned gesture on Home to run its action at once. Try always shows its confirmation, even with Show confirmations off.
- [x] **Quick Settings tile.** Add the **Snap Key** tile to turn the mapping on or off without opening the app. Long-press the tile to open the app.
- [x] **Back up and restore.** Save gesture actions, ringer presets, paused apps, timing, theme and the learned key to a file you choose, and restore them later. A gesture mapped to an app that is no longer installed shows "App not installed".
- [x] **Bug reports.** **Details** on the status card can copy a report with your versions, setup and last 20 detections, or open the bug form with its fields filled in. Reports name only the kind of each action, never contact numbers, links or app names.
- [x] **Safer teaching.** After teaching, press a different key, such as volume. The app keeps the learned key only if that press doesn't match it, and saves it only when you tap Save. Cancelling or a failed check keeps your previous settings.
- [x] **Clearer accessibility disclosure.** The service description, store listing and privacy page say that Android passes every hardware key press to the service and tells it which app is in front. The app acts only on the key you taught it.

## Delivered in v1.1.0

This release replaces v1.0.18 and includes its changes. It combines a review against Android's Compose, lifecycle and accessibility guidance with feedback from the [launch post](https://www.reddit.com/r/Oppo/comments/1xaze1m/i_built_an_app_to_remap_the_oppo_find_x9s_snap_key/). It was tested manually on a Find X9 running ColorOS 17. Behaviour on other firmware may differ.
Expand Down
4 changes: 2 additions & 2 deletions app/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ android {
minSdk = 29
targetSdk = 36
// F-Droid reads both as literals from this file.
versionCode = 10100
versionName = "1.1.0"
versionCode = 10200
versionName = "1.2.0"
}

// F-Droid can't inspect the dependency list that Google encrypts into the signing block.
Expand Down
18 changes: 18 additions & 0 deletions app/src/main/AndroidManifest.xml
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,26 @@
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<intent-filter>
<action android:name="android.service.quicksettings.action.QS_TILE_PREFERENCES" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>

<service
android:name=".SnapTileService"
android:exported="true"
android:label="@string/snap_tile_label"
android:icon="@drawable/ic_stat_snap"
android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
<intent-filter>
<action android:name="android.service.quicksettings.action.QS_TILE" />
</intent-filter>
<meta-data
android:name="android.service.quicksettings.TOGGLEABLE_TILE"
android:value="true" />
</service>

<service
android:name=".SnapAccessibilityService"
android:exported="true"
Expand Down
48 changes: 25 additions & 23 deletions app/src/main/java/com/heykay/snapkeymap/ActionRunner.kt
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,16 @@ object ActionRunner {
private var torchOn: Boolean? = null
private var torchWatched = false
private var torchUnavailable = false
private var pendingTorchToggle = false
// Null means no pending toggle; otherwise this carries that run's confirmation override.
private var pendingTorchToggle: Boolean? = null
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
private val ringerMutex = Mutex()

fun init(context: Context) {
runCatching { watchTorch(context.applicationContext) }
}

fun run(context: Context, action: SnapAction) {
fun run(context: Context, action: SnapAction, alwaysConfirm: Boolean = false) {
try {
when (action) {
SnapAction.NoAction -> Unit
Expand Down Expand Up @@ -70,8 +71,8 @@ object ActionRunner {
context,
Intent(Intent.ACTION_DIAL, Uri.parse("tel:" + Uri.encode(action.number))),
)
is SnapAction.Device -> runDevice(context, action.action)
is SnapAction.Ringer -> cycleRinger(context, action)
is SnapAction.Device -> runDevice(context, action.action, alwaysConfirm)
is SnapAction.Ringer -> cycleRinger(context, action, alwaysConfirm)
}
} catch (e: ActivityNotFoundException) {
toast(context, "No app can do that: ${action.label}")
Expand All @@ -80,10 +81,10 @@ object ActionRunner {
}
}

private fun runDevice(context: Context, action: DeviceAction) {
private fun runDevice(context: Context, action: DeviceAction, alwaysConfirm: Boolean) {
when (action) {
DeviceAction.FLASHLIGHT -> toggleTorch(context)
DeviceAction.DO_NOT_DISTURB -> toggleDoNotDisturb(context)
DeviceAction.FLASHLIGHT -> toggleTorch(context, alwaysConfirm)
DeviceAction.DO_NOT_DISTURB -> toggleDoNotDisturb(context, alwaysConfirm)
DeviceAction.SCREENSHOT -> global(context, AccessibilityService.GLOBAL_ACTION_TAKE_SCREENSHOT)
DeviceAction.CIRCLE_TO_SEARCH -> if (!CircleToSearch.start()) {
toast(context, "Circle to Search isn't available. Set Google as your digital assistant app.")
Expand Down Expand Up @@ -158,26 +159,26 @@ object ActionRunner {
if (cameraId != torchCameraId) return
torchUnavailable = false
torchOn = enabled
if (pendingTorchToggle) {
pendingTorchToggle = false
run(app, SnapAction.Device(DeviceAction.FLASHLIGHT))
pendingTorchToggle?.let { alwaysConfirm ->
pendingTorchToggle = null
run(app, SnapAction.Device(DeviceAction.FLASHLIGHT), alwaysConfirm)
}
}

override fun onTorchModeUnavailable(cameraId: String) {
if (cameraId != torchCameraId) return
torchUnavailable = true
torchOn = null
if (pendingTorchToggle) toast(app, "Flashlight isn't available while the camera is in use")
pendingTorchToggle = false
if (pendingTorchToggle != null) toast(app, "Flashlight isn't available while the camera is in use")
pendingTorchToggle = null
}
}, Handler(Looper.getMainLooper()))
torchWatched = true
}
return id
}

private fun toggleTorch(context: Context) {
private fun toggleTorch(context: Context, alwaysConfirm: Boolean) {
val id = watchTorch(context)
if (id == null) {
toast(context, "This phone has no flashlight")
Expand All @@ -190,19 +191,20 @@ object ActionRunner {
val current = torchOn
if (current == null) {
// Registration delivers the real initial state asynchronously, including Quick Settings changes.
pendingTorchToggle = !pendingTorchToggle
pendingTorchToggle = if (pendingTorchToggle == null) alwaysConfirm else null
return
}
context.getSystemService(CameraManager::class.java).setTorchMode(id, !current)
torchOn = !current
if (alwaysConfirm) confirm(context, if (current) "Flashlight off" else "Flashlight on", alwaysConfirm)
}

private fun cycleRinger(context: Context, action: SnapAction.Ringer) {
private fun cycleRinger(context: Context, action: SnapAction.Ringer, alwaysConfirm: Boolean) {
val app = context.applicationContext
scope.launch {
ringerMutex.withLock {
try {
changeRinger(app, action)
changeRinger(app, action, alwaysConfirm)
} catch (e: CancellationException) {
throw e
} catch (e: Exception) {
Expand All @@ -212,7 +214,7 @@ object ActionRunner {
}
}

private suspend fun changeRinger(context: Context, action: SnapAction.Ringer) {
private suspend fun changeRinger(context: Context, action: SnapAction.Ringer, alwaysConfirm: Boolean) {
val audio = context.getSystemService(AudioManager::class.java)
val externalMode = audio.ringerMode
// Before Android 15, `cmd audio` has no set-ringer-mode yet still exits 0, so success can't be trusted.
Expand All @@ -231,7 +233,7 @@ object ActionRunner {
}
if (result?.exitCode == 0) {
vibrateRinger(context, next)
confirm(context, next.label)
confirm(context, next.label, alwaysConfirm)
return
}
}
Expand All @@ -242,7 +244,7 @@ object ActionRunner {
audio.ringerMode = next.audioMode
vibrateRinger(context, next)
if (skippedSilent) toast(context, "Allow Do Not Disturb access to use Silent")
else confirm(context, next.label)
else confirm(context, next.label, alwaysConfirm)
}

private fun ringerMode(mode: Int): RingerMode? = when (mode) {
Expand Down Expand Up @@ -272,7 +274,7 @@ object ActionRunner {
RingerMode.SILENT -> AudioManager.RINGER_MODE_SILENT
}

private fun toggleDoNotDisturb(context: Context) {
private fun toggleDoNotDisturb(context: Context, alwaysConfirm: Boolean) {
val notifications = context.getSystemService(NotificationManager::class.java)
if (!notifications.isNotificationPolicyAccessGranted) {
toast(context, "Allow SnapKey Map to change Do Not Disturb")
Expand All @@ -283,11 +285,11 @@ object ActionRunner {
notifications.setInterruptionFilter(
if (turnOn) NotificationManager.INTERRUPTION_FILTER_PRIORITY else NotificationManager.INTERRUPTION_FILTER_ALL,
)
confirm(context, if (turnOn) "Do Not Disturb on" else "Do Not Disturb off")
confirm(context, if (turnOn) "Do Not Disturb on" else "Do Not Disturb off", alwaysConfirm)
}

private fun confirm(context: Context, text: String) {
if (SnapEngine.store.config.value.showConfirmations) toast(context, text)
private fun confirm(context: Context, text: String, alwaysConfirm: Boolean) {
if (alwaysConfirm || SnapEngine.store.config.value.showConfirmations) toast(context, text)
}

private fun toast(context: Context, text: String) {
Expand Down
134 changes: 134 additions & 0 deletions app/src/main/java/com/heykay/snapkeymap/BugReport.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
package com.heykay.snapkeymap

import android.content.Context
import android.os.Build
import java.net.URLEncoder
import rikka.shizuku.Shizuku

data class ReportInfo(
val versionName: String,
val versionCode: Long,
val phoneModel: String,
val colorOsVersion: String,
val androidRelease: String,
val sdk: Int,
val shizukuState: String,
val detectionMode: String,
val hasLogPermission: Boolean,
)

fun gatherReportInfo(context: Context, config: Config, precise: Boolean): ReportInfo {
val version = context.packageManager.getPackageInfo(context.packageName, 0)
val colorOs = runCatching {
Class.forName("android.os.SystemProperties")
.getMethod("get", String::class.java)
.invoke(null, "ro.build.version.oplusrom") as String
}.getOrNull()?.takeIf { it.isNotBlank() } ?: "unknown"
val shizuku = runCatching {
when {
!Shizuku.pingBinder() -> "Not running"
canUseShizuku() -> "Running and allowed"
else -> "Running, not allowed"
}
}.getOrDefault("Unavailable")
return ReportInfo(
versionName = version.versionName ?: "unknown",
versionCode = version.longVersionCode,
phoneModel = Build.MODEL,
colorOsVersion = colorOs,
androidRelease = Build.VERSION.RELEASE,
sdk = Build.VERSION.SDK_INT,
shizukuState = shizuku,
detectionMode = when {
!config.needsLogAccess -> "Accessibility key events"
precise -> "Precise input via Shizuku"
else -> "System logs"
},
hasLogPermission = SnapEngine.hasLogPermission(),
)
}

internal fun learnedKeySummary(config: Config): String = listOf(
config.keyEvent?.let { "keyEvent: code=${it.keyCode}, scan=${it.scanCode}" } ?: "keyEvent: not set",
config.inputKey?.let { "inputKey: ${it.code}" } ?: "inputKey: not set",
config.logSignature?.let { "logSignature: tag=${it.tag}" } ?: "logSignature: not set",
config.logKeyCode?.let { "logKeyCode: $it" } ?: "logKeyCode: not set",
).joinToString("\n")

private fun actionKind(action: SnapAction): String = when (action) {
SnapAction.NoAction -> "Do nothing"
is SnapAction.OpenApp -> "Open an app"
is SnapAction.OpenShortcut -> "Open a shortcut"
is SnapAction.OpenLink -> "Open a link"
is SnapAction.CallContact -> "Call a contact"
is SnapAction.Device -> action.action.label
is SnapAction.Ringer -> "Ringer: ${action.modes.joinToString(" → ") { it.label }}"
}

private fun actionsSummary(config: Config): String = Gesture.entries.joinToString("\n") { gesture ->
"${gesture.title}: ${actionKind(config.action(gesture))}; unlocked-only: ${if (gesture in config.unlockedOnly) "on" else "off"}"
}

private fun detectionText(detected: SnapEngine.Detected, timeFormat: (Long) -> String): String =
"${detected.gesture.title} at ${timeFormat(detected.atMs)} [${detected.source}]"

fun buildReport(
info: ReportInfo,
config: Config,
detections: List<SnapEngine.Detected>,
timeFormat: (Long) -> String,
): String = buildString {
appendLine("SnapKey Map ${info.versionName} (${info.versionCode})")
appendLine("Phone: ${info.phoneModel}")
appendLine("ColorOS: ${info.colorOsVersion}")
appendLine("Android: ${info.androidRelease} (SDK ${info.sdk})")
appendLine("Grant method: ${grantMethodText(config.grantMethod)}")
appendLine("Log permission: ${if (info.hasLogPermission) "granted" else "not granted"}")
appendLine("Shizuku: ${info.shizukuState}")
appendLine("Detection mode: ${info.detectionMode}")
appendLine(learnedKeySummary(config))
appendLine("Double-press window: ${config.doublePressWindowMs} ms")
appendLine("Hold threshold: ${config.holdMs} ms")
appendLine()
appendLine(actionsSummary(config))
appendLine()
appendLine("Last $DETECTION_HISTORY_SIZE detections:")
if (detections.isEmpty()) appendLine("None yet")
else detections.takeLast(DETECTION_HISTORY_SIZE).forEach { appendLine(detectionText(it, timeFormat)) }
}.trimEnd()

private fun grantMethodText(method: GrantMethod?): String = when (method) {
GrantMethod.SHIZUKU -> "Shizuku"
GrantMethod.ADB -> "Computer (ADB)"
null -> "Not granted yet"
}

fun bugReportUrl(
info: ReportInfo,
config: Config,
last: SnapEngine.Detected?,
timeFormat: (Long) -> String,
): String {
val logAccess = if (config.needsLogAccess && !info.hasLogPermission) "Not granted yet"
else grantMethodText(config.grantMethod)
val fields = listOf(
"app-version" to encodeReportField("${info.versionName} (${info.versionCode})", 100),
"device" to encodeReportField("${info.phoneModel}, ColorOS ${info.colorOsVersion}, Android ${info.androidRelease} (SDK ${info.sdk})", 300),
"log-access" to encodeReportField(logAccess, 100),
"teach" to encodeReportField(learnedKeySummary(config), 400),
"actions" to encodeReportField(actionsSummary(config) + "\nLast: " +
(last?.let { detectionText(it, timeFormat) } ?: "None yet"), 700),
)
return "https://github.com/heykay-47/SnapKeyMap/issues/new?template=bug_report.yml&" +
fields.joinToString("&") { (key, value) -> "$key=$value" }
}

private fun encodeReportField(value: String, maxLength: Int): String {
var text = value.take(maxLength)
var encoded = URLEncoder.encode(text, "UTF-8").replace("+", "%20")
while (encoded.length > maxLength) {
text = text.dropLast(1)
encoded = URLEncoder.encode(text, "UTF-8").replace("+", "%20")
}
return encoded
}
Loading
Loading