Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

fix(terminal): apply sticky and hardware modifiers to special keys

ExTvf236ad4ad216
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalKeyEncoder.kt b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalKeyEncoder.kt
new file mode 100644
index 0000000..1a1b052
--- /dev/null
+++ b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalKeyEncoder.kt
@@ -0,0 +1,115 @@
+/*
+ * Podroid - Rootless Podman for Android
+ * Copyright (C) 2024-2026 Podroid contributors
+ *
+ * Pure xterm key-sequence encoding shared by TerminalViewModel's onKeyDown
+ * (hardware/soft keyboard) and sendExtraKey (the extra keys row), so both
+ * apply the sticky CTRL/ALT modifiers the same way.
+ */
+package com.excp.podroid.ui.screens.terminal
+
+import android.view.KeyEvent
+
+/** xterm CSI modifier: 1=none, 2=shift, 3=alt, 4=shift+alt, 5=ctrl,
+ * 6=ctrl+shift, 7=ctrl+alt, 8=all. Used for "ESC [1;<m><final>" /
+ * "ESC [<n>;<m>~" sequences. */
+fun xtermModifier(shift: Boolean, alt: Boolean, ctrl: Boolean): Int =
+ 1 + (if (shift) 1 else 0) + (if (alt) 2 else 0) + (if (ctrl) 4 else 0)
+
+enum class TermKey {
+ UP, DOWN, RIGHT, LEFT, HOME, END,
+ PAGE_UP, PAGE_DOWN, INSERT, DELETE,
+ F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
+}
+
+// Cursor keys and HOME/END: "ESC O x" (application mode) / "ESC [ x" (normal
+// mode) when unmodified, "ESC [ 1 ; mod x" when modified.
+private val CURSOR_FINAL = mapOf(
+ TermKey.UP to 'A', TermKey.DOWN to 'B', TermKey.RIGHT to 'C', TermKey.LEFT to 'D',
+ TermKey.HOME to 'H', TermKey.END to 'F',
+)
+
+// F1-F4: "ESC O x" when unmodified, "ESC [ 1 ; mod x" when modified.
+private val SS3_FINAL = mapOf(
+ TermKey.F1 to 'P', TermKey.F2 to 'Q', TermKey.F3 to 'R', TermKey.F4 to 'S',
+)
+
+// PAGE_UP/PAGE_DOWN/INSERT/DELETE/F5-F12: "ESC [ n ~" when unmodified,
+// "ESC [ n ; mod ~" when modified.
+private val TILDE_N = mapOf(
+ TermKey.INSERT to 2, TermKey.DELETE to 3, TermKey.PAGE_UP to 5, TermKey.PAGE_DOWN to 6,
+ TermKey.F5 to 15, TermKey.F6 to 17, TermKey.F7 to 18, TermKey.F8 to 19, TermKey.F9 to 20,
+ TermKey.F10 to 21, TermKey.F11 to 23, TermKey.F12 to 24,
+)
+
+/** Encodes [key] as the xterm byte sequence for modifier [mod] (see
+ * [xtermModifier]), honoring [appCursor] (DECCKM) for the cursor keys group. */
+fun encode(key: TermKey, mod: Int, appCursor: Boolean): ByteArray {
+ CURSOR_FINAL[key]?.let { final ->
+ return if (mod == 1) {
+ if (appCursor) "\u001BO$final".toByteArray() else "\u001B[$final".toByteArray()
+ } else {
+ "\u001B[1;$mod$final".toByteArray()
+ }
+ }
+ SS3_FINAL[key]?.let { final ->
+ return if (mod == 1) "\u001BO$final".toByteArray() else "\u001B[1;$mod$final".toByteArray()
+ }
+ val n = TILDE_N.getValue(key)
+ return if (mod == 1) "\u001B[$n~".toByteArray() else "\u001B[$n;$mod~".toByteArray()
+}
+
+/** Maps a hardware/soft keyboard key code to the [TermKey] it encodes, or
+ * null when [keyCode] is handled elsewhere (ENTER/DEL/TAB/ESCAPE) or not a
+ * terminal key at all. */
+fun termKeyForKeyCode(keyCode: Int): TermKey? = when (keyCode) {
+ KeyEvent.KEYCODE_DPAD_UP -> TermKey.UP
+ KeyEvent.KEYCODE_DPAD_DOWN -> TermKey.DOWN
+ KeyEvent.KEYCODE_DPAD_RIGHT -> TermKey.RIGHT
+ KeyEvent.KEYCODE_DPAD_LEFT -> TermKey.LEFT
+ KeyEvent.KEYCODE_MOVE_HOME -> TermKey.HOME
+ KeyEvent.KEYCODE_MOVE_END -> TermKey.END
+ KeyEvent.KEYCODE_PAGE_UP -> TermKey.PAGE_UP
+ KeyEvent.KEYCODE_PAGE_DOWN -> TermKey.PAGE_DOWN
+ KeyEvent.KEYCODE_INSERT -> TermKey.INSERT
+ KeyEvent.KEYCODE_FORWARD_DEL -> TermKey.DELETE
+ KeyEvent.KEYCODE_F1 -> TermKey.F1
+ KeyEvent.KEYCODE_F2 -> TermKey.F2
+ KeyEvent.KEYCODE_F3 -> TermKey.F3
+ KeyEvent.KEYCODE_F4 -> TermKey.F4
+ KeyEvent.KEYCODE_F5 -> TermKey.F5
+ KeyEvent.KEYCODE_F6 -> TermKey.F6
+ KeyEvent.KEYCODE_F7 -> TermKey.F7
+ KeyEvent.KEYCODE_F8 -> TermKey.F8
+ KeyEvent.KEYCODE_F9 -> TermKey.F9
+ KeyEvent.KEYCODE_F10 -> TermKey.F10
+ KeyEvent.KEYCODE_F11 -> TermKey.F11
+ KeyEvent.KEYCODE_F12 -> TermKey.F12
+ else -> null
+}
+
+/** Maps an extra-keys row label to the [TermKey] it encodes, or null when
+ * [label] is handled elsewhere (CTRL/ALT/PASTE/ESC/TAB/-/|/) or unknown. */
+fun termKeyForLabel(label: String): TermKey? = when (label) {
+ "UP" -> TermKey.UP
+ "DOWN" -> TermKey.DOWN
+ "LEFT" -> TermKey.LEFT
+ "RIGHT" -> TermKey.RIGHT
+ "HOME" -> TermKey.HOME
+ "END" -> TermKey.END
+ "PGUP" -> TermKey.PAGE_UP
+ "PGDN" -> TermKey.PAGE_DOWN
+ "F1" -> TermKey.F1
+ "F2" -> TermKey.F2
+ "F3" -> TermKey.F3
+ "F4" -> TermKey.F4
+ "F5" -> TermKey.F5
+ "F6" -> TermKey.F6
+ "F7" -> TermKey.F7
+ "F8" -> TermKey.F8
+ "F9" -> TermKey.F9
+ "F10" -> TermKey.F10
+ "F11" -> TermKey.F11
+ "F12" -> TermKey.F12
+ else -> null
+}
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt
index 6e2c01f..9f52d57 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/terminal/TerminalViewModel.kt
@@ -645,47 +645,16 @@ class TerminalViewModel @Inject constructor(
val shift = e.isShiftPressed
val ctrl = e.isCtrlPressed || extraCtrl
val alt = e.isAltPressed || extraAlt
- // xterm CSI modifier: 1=none, 2=shift, 3=alt, 4=shift+alt, 5=ctrl,
- // 6=ctrl+shift, 7=ctrl+alt, 8=all. Used for "ESC [1;<m><final>".
- val mod = 1 + (if (shift) 1 else 0) + (if (alt) 2 else 0) + (if (ctrl) 4 else 0)
- val appCursor = cursorKeysApplicationMode(session?.emulator)
- fun arrow(final: Char): ByteArray =
- if (mod == 1) {
- if (cursorKeysApplicationMode(session?.emulator)) "\u001bO$final".toByteArray()
- else "\u001b[$final".toByteArray()
- } else {
- "\u001b[1;$mod$final".toByteArray()
- }
+ val mod = xtermModifier(shift, alt, ctrl)
val bytes = when (keyCode) {
- KeyEvent.KEYCODE_ENTER -> byteArrayOf(13)
- KeyEvent.KEYCODE_DEL -> byteArrayOf(127)
- KeyEvent.KEYCODE_FORWARD_DEL -> "\u001b[3~".toByteArray()
- KeyEvent.KEYCODE_TAB ->
- if (shift) "\u001b[Z".toByteArray() else byteArrayOf(9)
- KeyEvent.KEYCODE_ESCAPE -> byteArrayOf(27)
- KeyEvent.KEYCODE_DPAD_UP -> arrow('A')
- KeyEvent.KEYCODE_DPAD_DOWN -> arrow('B')
- KeyEvent.KEYCODE_DPAD_RIGHT -> arrow('C')
- KeyEvent.KEYCODE_DPAD_LEFT -> arrow('D')
- KeyEvent.KEYCODE_MOVE_HOME -> arrow('H')
- KeyEvent.KEYCODE_MOVE_END -> arrow('F')
- KeyEvent.KEYCODE_PAGE_UP -> "\u001b[5~".toByteArray()
- KeyEvent.KEYCODE_PAGE_DOWN -> "\u001b[6~".toByteArray()
- KeyEvent.KEYCODE_INSERT -> "\u001b[2~".toByteArray()
- KeyEvent.KEYCODE_F1 -> "\u001bOP".toByteArray()
- KeyEvent.KEYCODE_F2 -> "\u001bOQ".toByteArray()
- KeyEvent.KEYCODE_F3 -> "\u001bOR".toByteArray()
- KeyEvent.KEYCODE_F4 -> "\u001bOS".toByteArray()
- KeyEvent.KEYCODE_F5 -> "\u001b[15~".toByteArray()
- KeyEvent.KEYCODE_F6 -> "\u001b[17~".toByteArray()
- KeyEvent.KEYCODE_F7 -> "\u001b[18~".toByteArray()
- KeyEvent.KEYCODE_F8 -> "\u001b[19~".toByteArray()
- KeyEvent.KEYCODE_F9 -> "\u001b[20~".toByteArray()
- KeyEvent.KEYCODE_F10 -> "\u001b[21~".toByteArray()
- KeyEvent.KEYCODE_F11 -> "\u001b[23~".toByteArray()
- KeyEvent.KEYCODE_F12 -> "\u001b[24~".toByteArray()
- else -> null
+ KeyEvent.KEYCODE_ENTER -> byteArrayOf(13)
+ KeyEvent.KEYCODE_DEL -> byteArrayOf(127)
+ KeyEvent.KEYCODE_TAB -> if (shift) "\u001b[Z".toByteArray() else byteArrayOf(9)
+ KeyEvent.KEYCODE_ESCAPE -> byteArrayOf(27)
+ else -> termKeyForKeyCode(keyCode)?.let {
+ encode(it, mod, cursorKeysApplicationMode(session?.emulator))
+ }
}
if (bytes != null) {
session?.write(bytes, 0, bytes.size)
@@ -803,30 +772,13 @@ class TerminalViewModel @Inject constructor(
val bytes = when (key) {
"ESC" -> byteArrayOf(27)
"TAB" -> byteArrayOf(9)
- "UP" -> if (cursorKeysApplicationMode(session?.emulator)) "\u001bOA".toByteArray() else "\u001b[A".toByteArray()
- "DOWN" -> if (cursorKeysApplicationMode(session?.emulator)) "\u001bOB".toByteArray() else "\u001b[B".toByteArray()
- "LEFT" -> if (cursorKeysApplicationMode(session?.emulator)) "\u001bOD".toByteArray() else "\u001b[D".toByteArray()
- "RIGHT"-> if (cursorKeysApplicationMode(session?.emulator)) "\u001bOC".toByteArray() else "\u001b[C".toByteArray()
- "HOME" -> if (cursorKeysApplicationMode(session?.emulator)) "\u001bOH".toByteArray() else "\u001b[H".toByteArray()
- "END" -> if (cursorKeysApplicationMode(session?.emulator)) "\u001bOF".toByteArray() else "\u001b[F".toByteArray()
- "PGUP" -> "\u001b[5~".toByteArray()
- "PGDN" -> "\u001b[6~".toByteArray()
- "F1" -> "\u001bOP".toByteArray()
- "F2" -> "\u001bOQ".toByteArray()
- "F3" -> "\u001bOR".toByteArray()
- "F4" -> "\u001bOS".toByteArray()
- "F5" -> "\u001b[15~".toByteArray()
- "F6" -> "\u001b[17~".toByteArray()
- "F7" -> "\u001b[18~".toByteArray()
- "F8" -> "\u001b[19~".toByteArray()
- "F9" -> "\u001b[20~".toByteArray()
- "F10" -> "\u001b[21~".toByteArray()
- "F11" -> "\u001b[23~".toByteArray()
- "F12" -> "\u001b[24~".toByteArray()
- "-" -> "-".toByteArray()
- "|" -> "|".toByteArray()
- "/" -> "/".toByteArray()
- else -> return
+ "-" -> if (extraAlt) byteArrayOf(27) + "-".toByteArray() else "-".toByteArray()
+ "|" -> if (extraAlt) byteArrayOf(27) + "|".toByteArray() else "|".toByteArray()
+ "/" -> if (extraAlt) byteArrayOf(27) + "/".toByteArray() else "/".toByteArray()
+ else -> termKeyForLabel(key)?.let {
+ val mod = xtermModifier(false, extraAlt, extraCtrl)
+ encode(it, mod, cursorKeysApplicationMode(session?.emulator))
+ } ?: return
}
session?.write(bytes, 0, bytes.size)
extraCtrl = false
diff --git a/app/src/test/java/com/excp/podroid/ui/screens/terminal/TerminalKeyEncoderTest.kt b/app/src/test/java/com/excp/podroid/ui/screens/terminal/TerminalKeyEncoderTest.kt
new file mode 100644
index 0000000..0c68f3d
--- /dev/null
+++ b/app/src/test/java/com/excp/podroid/ui/screens/terminal/TerminalKeyEncoderTest.kt
@@ -0,0 +1,81 @@
+/*
+ * Podroid - Rootless Podman for Android
+ * Copyright (C) 2024-2026 Podroid contributors
+ */
+package com.excp.podroid.ui.screens.terminal
+
+import android.view.KeyEvent
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class TerminalKeyEncoderTest {
+
+ @Test fun `xtermModifier combines shift alt ctrl bits`() {
+ assertEquals(1, xtermModifier(shift = false, alt = false, ctrl = false))
+ assertEquals(8, xtermModifier(shift = true, alt = true, ctrl = true))
+ }
+
+ @Test fun `UP with mod 1 uses CSI or SS3 depending on appCursor`() {
+ assertEquals("\u001B[A", String(encode(TermKey.UP, 1, appCursor = false)))
+ assertEquals("\u001BOA", String(encode(TermKey.UP, 1, appCursor = true)))
+ }
+
+ @Test fun `UP with ctrl modifier ignores appCursor`() {
+ val mod = xtermModifier(shift = false, alt = false, ctrl = true)
+ assertEquals("\u001B[1;5A", String(encode(TermKey.UP, mod, appCursor = true)))
+ }
+
+ @Test fun `HOME with mod 1 and appCursor uses SS3`() {
+ assertEquals("\u001BOH", String(encode(TermKey.HOME, 1, appCursor = true)))
+ }
+
+ @Test fun `PAGE_UP with mod 1 is unmodified tilde sequence`() {
+ assertEquals("\u001B[5~", String(encode(TermKey.PAGE_UP, 1, appCursor = false)))
+ }
+
+ @Test fun `PAGE_UP with ctrl adds the modifier to the tilde sequence`() {
+ val mod = xtermModifier(shift = false, alt = false, ctrl = true)
+ assertEquals("\u001B[5;5~", String(encode(TermKey.PAGE_UP, mod, appCursor = false)))
+ }
+
+ @Test fun `F1 with mod 1 uses SS3`() {
+ assertEquals("\u001BOP", String(encode(TermKey.F1, 1, appCursor = false)))
+ }
+
+ @Test fun `F1 with shift switches to the CSI form`() {
+ val mod = xtermModifier(shift = true, alt = false, ctrl = false)
+ assertEquals("\u001B[1;2P", String(encode(TermKey.F1, mod, appCursor = false)))
+ }
+
+ @Test fun `F12 with alt adds the modifier to the tilde sequence`() {
+ val mod = xtermModifier(shift = false, alt = true, ctrl = false)
+ assertEquals("\u001B[24;3~", String(encode(TermKey.F12, mod, appCursor = false)))
+ }
+
+ @Test fun `DELETE with mod 1 is the unmodified tilde sequence`() {
+ assertEquals("\u001B[3~", String(encode(TermKey.DELETE, 1, appCursor = false)))
+ }
+
+ @Test fun `termKeyForKeyCode maps hardware key codes`() {
+ assertEquals(TermKey.UP, termKeyForKeyCode(KeyEvent.KEYCODE_DPAD_UP))
+ assertEquals(TermKey.PAGE_DOWN, termKeyForKeyCode(KeyEvent.KEYCODE_PAGE_DOWN))
+ assertEquals(TermKey.DELETE, termKeyForKeyCode(KeyEvent.KEYCODE_FORWARD_DEL))
+ assertEquals(TermKey.F12, termKeyForKeyCode(KeyEvent.KEYCODE_F12))
+ }
+
+ @Test fun `termKeyForKeyCode returns null for an unmapped key code`() {
+ assertNull(termKeyForKeyCode(KeyEvent.KEYCODE_A))
+ }
+
+ @Test fun `termKeyForLabel maps extra-keys row labels`() {
+ assertEquals(TermKey.HOME, termKeyForLabel("HOME"))
+ assertEquals(TermKey.PAGE_UP, termKeyForLabel("PGUP"))
+ assertEquals(TermKey.F1, termKeyForLabel("F1"))
+ }
+
+ @Test fun `termKeyForLabel returns null for an unmapped label`() {
+ assertNull(termKeyForLabel("CTRL"))
+ assertNull(termKeyForLabel("-"))
+ }
+}