Customize shortcut modifier and forward Ctrl and Shift to the device

README.md

@@ -354,7 +354,7 @@ scrcpy --fullscreen
 scrcpy -f  # short version
 ```
 
-Fullscreen can then be toggled dynamically with `Ctrl`+`f`.
+Fullscreen can then be toggled dynamically with `MOD`+`f`.
 
 #### Rotation
 
@@ -370,17 +370,17 @@ Possibles values are:
  - `2`: 180 degrees
  - `3`: 90 degrees clockwise
 
-The rotation can also be changed dynamically with `Ctrl`+`←` _(left)_ and
-`Ctrl`+`→` _(right)_.
+The rotation can also be changed dynamically with `MOD`+`←` _(left)_ and
+`MOD`+`→` _(right)_.
 
 Note that _scrcpy_ manages 3 different rotations:
- - `Ctrl`+`r` requests the device to switch between portrait and landscape (the
+ - `MOD`+`r` requests the device to switch between portrait and landscape (the
    current running app may refuse, if it does support the requested
    orientation).
  - `--lock-video-orientation` changes the mirroring orientation (the orientation
    of the video sent from the device to the computer). This affects the
    recording.
- - `--rotation` (or `Ctrl`+`←`/`Ctrl`+`→`) rotates only the window content. This
+ - `--rotation` (or `MOD`+`←`/`MOD`+`→`) rotates only the window content. This
    affects only the display, not the recording.
 
 
@@ -437,9 +437,9 @@ scrcpy --turn-screen-off
 scrcpy -S
 ```
 
-Or by pressing `Ctrl`+`o` at any time.
+Or by pressing `MOD`+`o` at any time.
 
-To turn it back on, press `Ctrl`+`Shift`+`o` (or `POWER`, `Ctrl`+`p`).
+To turn it back on, press `MOD`+`Shift`+`o` (or `POWER`, `MOD`+`p`).
 
 It can be useful to also prevent the device to sleep:
 
@@ -494,24 +494,42 @@ scrcpy --disable-screensaver
 
 #### Rotate device screen
 
-Press `Ctrl`+`r` to switch between portrait and landscape modes.
+Press `MOD`+`r` to switch between portrait and landscape modes.
 
 Note that it rotates only if the application in foreground supports the
 requested orientation.
 
 #### Copy-paste
 
-It is possible to synchronize clipboards between the computer and the device, in
-both directions:
+Any time the Android clipboard changes, it is automatically synchronized to the
+computer clipboard.
 
- - `Ctrl`+`c` copies the device clipboard to the computer clipboard;
- - `Ctrl`+`Shift`+`v` copies the computer clipboard to the device clipboard (and
-   pastes if the device runs Android >= 7);
- - `Ctrl`+`v` _pastes_ the computer clipboard as a sequence of text events (but
-   breaks non-ASCII characters).
+Any `Ctrl` shortcut is forwarded to the device. In particular:
+ - `Ctrl`+`c` typically copies
+ - `Ctrl`+`x` typically cuts
+ - `Ctrl`+`v` typically pastes (after computer-to-device clipboard
+   synchronization)
 
-Moreover, any time the Android clipboard changes, it is automatically
-synchronized to the computer clipboard.
+This typically works as you expect.
+
+The actual behavior depends on the active application though. For example,
+_Termux_ sends SIGINT on `Ctrl`+`c` instead, and _K-9 Mail_ composes a new
+message.
+
+To copy, cut and paste in such cases (but only supported on Android >= 7):
+ - `MOD`+`c` injects `COPY`
+ - `MOD`+`x` injects `CUT`
+ - `MOD`+`v` injects `PASTE` (after computer-to-device clipboard
+   synchronization)
+
+In addition, `MOD`+`Shift`+`v` allows to inject the computer clipboard text as a
+sequence of key events. This is useful when the component does not accept text
+pasting (for example in _Termux_), but it can break non-ASCII content.
+
+**WARNING:** Pasting the computer clipboard to the device (either via `Ctrl`+`v`
+or `MOD`+`v`) copies the content into the device clipboard. As a consequence,
+any Android application could read its content. You should avoid to paste
+sensitive content (like passwords) that way.
 
 #### Text injection preference
 
@@ -571,33 +589,56 @@ Also see [issue #14].
 
 ## Shortcuts
 
- | Action                                      |   Shortcut                    |   Shortcut (macOS)
- | ------------------------------------------- |:----------------------------- |:-----------------------------
- | Switch fullscreen mode                      | `Ctrl`+`f`                    | `Cmd`+`f`
- | Rotate display left                         | `Ctrl`+`←` _(left)_           | `Cmd`+`←` _(left)_
- | Rotate display right                        | `Ctrl`+`→` _(right)_          | `Cmd`+`→` _(right)_
- | Resize window to 1:1 (pixel-perfect)        | `Ctrl`+`g`                    | `Cmd`+`g`
- | Resize window to remove black borders       | `Ctrl`+`x` \| _Double-click¹_ | `Cmd`+`x`  \| _Double-click¹_
- | Click on `HOME`                             | `Ctrl`+`h` \| _Middle-click_  | `Ctrl`+`h` \| _Middle-click_
- | Click on `BACK`                             | `Ctrl`+`b` \| _Right-click²_  | `Cmd`+`b`  \| _Right-click²_
- | Click on `APP_SWITCH`                       | `Ctrl`+`s`                    | `Cmd`+`s`
- | Click on `MENU`                             | `Ctrl`+`m`                    | `Ctrl`+`m`
- | Click on `VOLUME_UP`                        | `Ctrl`+`↑` _(up)_             | `Cmd`+`↑` _(up)_
- | Click on `VOLUME_DOWN`                      | `Ctrl`+`↓` _(down)_           | `Cmd`+`↓` _(down)_
- | Click on `POWER`                            | `Ctrl`+`p`                    | `Cmd`+`p`
- | Power on                                    | _Right-click²_                | _Right-click²_
- | Turn device screen off (keep mirroring)     | `Ctrl`+`o`                    | `Cmd`+`o`
- | Turn device screen on                       | `Ctrl`+`Shift`+`o`            | `Cmd`+`Shift`+`o`
- | Rotate device screen                        | `Ctrl`+`r`                    | `Cmd`+`r`
- | Expand notification panel                   | `Ctrl`+`n`                    | `Cmd`+`n`
- | Collapse notification panel                 | `Ctrl`+`Shift`+`n`            | `Cmd`+`Shift`+`n`
- | Copy device clipboard to computer           | `Ctrl`+`c`                    | `Cmd`+`c`
- | Paste computer clipboard to device          | `Ctrl`+`v`                    | `Cmd`+`v`
- | Copy computer clipboard to device and paste | `Ctrl`+`Shift`+`v`            | `Cmd`+`Shift`+`v`
- | Enable/disable FPS counter (on stdout)      | `Ctrl`+`i`                    | `Cmd`+`i`
+In the following list, `MOD` is the shortcut modifier. By default, it's (left)
+`Alt` or (left) `Super`.
+
+It can be changed using `--shortcut-mod`. Possible keys are `lctrl`, `rctrl`,
+`lalt`, `ralt`, `lsuper` and `rsuper`. For example:
+
+```bash
+# use RCtrl for shortcuts
+scrcpy --shortcut-mod=rctrl
+
+# use either LCtrl+LAlt or LSuper for shortcuts
+scrcpy --shortcut-mod=lctrl+lalt,lsuper
+```
+
+_[Super] is typically the "Windows" or "Cmd" key._
+
+[Super]: https://en.wikipedia.org/wiki/Super_key_(keyboard_button)
+
+ | Action                                      |   Shortcut
+ | ------------------------------------------- |:-----------------------------
+ | Switch fullscreen mode                      | `MOD`+`f`
+ | Rotate display left                         | `MOD`+`←` _(left)_
+ | Rotate display right                        | `MOD`+`→` _(right)_
+ | Resize window to 1:1 (pixel-perfect)        | `MOD`+`g`
+ | Resize window to remove black borders       | `MOD`+`w` \| _Double-click¹_
+ | Click on `HOME`                             | `MOD`+`h` \| _Middle-click_
+ | Click on `BACK`                             | `MOD`+`b` \| _Right-click²_
+ | Click on `APP_SWITCH`                       | `MOD`+`s`
+ | Click on `MENU`                             | `MOD`+`m`
+ | Click on `VOLUME_UP`                        | `MOD`+`↑` _(up)_
+ | Click on `VOLUME_DOWN`                      | `MOD`+`↓` _(down)_
+ | Click on `POWER`                            | `MOD`+`p`
+ | Power on                                    | _Right-click²_
+ | Turn device screen off (keep mirroring)     | `MOD`+`o`
+ | Turn device screen on                       | `MOD`+`Shift`+`o`
+ | Rotate device screen                        | `MOD`+`r`
+ | Expand notification panel                   | `MOD`+`n`
+ | Collapse notification panel                 | `MOD`+`Shift`+`n`
+ | Copy to clipboard³                          | `MOD`+`c`
+ | Cut to clipboard³                           | `MOD`+`x`
+ | Synchronize clipboards and paste³           | `MOD`+`v`
+ | Inject computer clipboard text              | `MOD`+`Shift`+`v`
+ | Enable/disable FPS counter (on stdout)      | `MOD`+`i`
 
 _¹Double-click on black borders to remove them._  
-_²Right-click turns the screen on if it was off, presses BACK otherwise._
+_²Right-click turns the screen on if it was off, presses BACK otherwise._  
+_³Only on Android >= 7._
+
+All `Ctrl`+_key_ shortcuts are forwarded to the device, so they are handled by
+the active application.
 
 
 ## Custom paths

app/meson.build

@@ -186,7 +186,7 @@ if get_option('buildtype') == 'debug'
         exe = executable(t[0], t[1],
                          include_directories: src_dir,
                          dependencies: dependencies,
-                         c_args: ['-DSDL_MAIN_HANDLED'])
+                         c_args: ['-DSDL_MAIN_HANDLED', '-DSC_TEST'])
         test(t[0], exe)
     endforeach
 endif

app/scrcpy.1

@@ -149,6 +149,16 @@ Set the initial display rotation. Possibles values are 0, 1, 2 and 3. Each incre
 .BI "\-s, \-\-serial " number
 The device serial number. Mandatory only if several devices are connected to adb.
 
+.TP
+.BI "\-\-shortcut\-mod " key[+...]][,...]
+Specify the modifiers to use for scrcpy shortcuts. Possible keys are "lctrl", "rctrl", "lalt", "ralt", "lsuper" and "rsuper".
+
+A shortcut can consist in several keys, separated by '+'. Several shortcuts can be specified, separated by ','.
+
+For example, to use either LCtrl+LAlt or LSuper for scrcpy shortcuts, pass "lctrl+lalt,lsuper".
+
+Default is "lalt,lsuper" (left-Alt or left-Super).
+
 .TP
 .B \-S, \-\-turn\-screen\-off
 Turn the device screen off immediately.
@@ -207,92 +217,99 @@ Default is 0 (automatic).\n
 
 .SH SHORTCUTS
 
+In the following list, MOD is the shortcut modifier. By default, it's (left)
+Alt or (left) Super, but it can be configured by \-\-shortcut-mod.
+
 .TP
-.B Ctrl+f
+.B MOD+f
 Switch fullscreen mode
 
 .TP
-.B Ctrl+Left
+.B MOD+Left
 Rotate display left
 
 .TP
-.B Ctrl+Right
+.B MOD+Right
 Rotate display right
 
 .TP
-.B Ctrl+g
+.B MOD+g
 Resize window to 1:1 (pixel\-perfect)
 
 .TP
-.B Ctrl+x, Double\-click on black borders
+.B MOD+w, Double\-click on black borders
 Resize window to remove black borders
 
 .TP
-.B Ctrl+h, Home, Middle\-click
+.B MOD+h, Home, Middle\-click
 Click on HOME
 
 .TP
-.B Ctrl+b, Ctrl+Backspace, Right\-click (when screen is on)
+.B MOD+b, MOD+Backspace, Right\-click (when screen is on)
 Click on BACK
 
 .TP
-.B Ctrl+s
+.B MOD+s
 Click on APP_SWITCH
 
 .TP
-.B Ctrl+m
+.B MOD+m
 Click on MENU
 
 .TP
-.B Ctrl+Up
+.B MOD+Up
 Click on VOLUME_UP
 
 .TP
-.B Ctrl+Down
+.B MOD+Down
 Click on VOLUME_DOWN
 
 .TP
-.B Ctrl+p
+.B MOD+p
 Click on POWER (turn screen on/off)
 
 .TP
 .B Right\-click (when screen is off)
 Turn screen on
 
 .TP
-.B Ctrl+o
+.B MOD+o
 Turn device screen off (keep mirroring)
 
 .TP
-.B Ctrl+Shift+o
+.B MOD+Shift+o
 Turn device screen on
 
 .TP
-.B Ctrl+r
+.B MOD+r
 Rotate device screen
 
 .TP
-.B Ctrl+n
+.B MOD+n
 Expand notification panel
 
 .TP
-.B Ctrl+Shift+n
+.B MOD+Shift+n
 Collapse notification panel
 
 .TP
-.B Ctrl+c
-Copy device clipboard to computer
+.B Mod+c
+Copy to clipboard (inject COPY keycode, Android >= 7 only)
+
+.TP
+.B Mod+x
+Cut to clipboard (inject CUT keycode, Android >= 7 only)
 
 .TP
-.B Ctrl+v
-Paste computer clipboard to device
+.B MOD+v
+Copy computer clipboard to device, then paste (inject PASTE keycode, Android >= 7 only)
 
 .TP
-.B Ctrl+Shift+v
-Copy computer clipboard to device (and paste if the device runs Android >= 7)
+.B MOD+Shift+v
+Inject computer clipboard text as a sequence of key events
 
 .TP
-.B Ctrl+i
+.B MOD+i
 Enable/disable FPS counter (print frames/second in logs)
 
 .TP