docs: add reference to WinApps Launcher as optional system tray tool

Add protocol handler for Microsoft Office links (e.g. ms-office://)

.github/workflows/update-submodule.yaml

@@ -1,37 +0,0 @@
-name: Update submodules
-on:
-  repository_dispatch:
-    types: update
-
-jobs:
-  update:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          submodules: recursive
-
-      - name: Update module
-        run: |
-          pushd WinApps-Launcher
-            branch=$(git rev-parse --abbrev-ref origin/HEAD | sed "s|origin/||")
-            git config remote.origin.fetch "+refs/heads/$branch:refs/remotes/origin/$branch"
-            git fetch --depth=1 origin "refs/heads/$branch"
-          popd
-
-          git submodule update --init --remote WinApps-Launcher
-
-      - name: Commit and push
-        uses: EndBug/add-and-commit@v9
-        with:
-          add: WinApps-Launcher
-          default_author: github_actions
-          message: "Update submodules"
-          push: false
-
-      - name: Create PR
-        uses: peter-evans/create-pull-request@v7
-        with:
-          branch: chore/update_submodules
-          delete-branch: true
-          title: "Update submodules"

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "WinApps-Launcher"]
-	path = WinApps-Launcher
-	url = https://github.com/winapps-org/WinApps-Launcher.git

README.md

@@ -17,6 +17,7 @@ WinApps works by:
 - The GNU/Linux `/home` directory is accessible within Windows via the `\\tsclient\home` mount.
 - Integration with `Nautilus`, allowing you to right-click files to open them with specific Windows applications based on the file MIME type.
 - The [official taskbar widget](https://github.com/winapps-org/WinApps-Launcher) enables seamless administration of the Windows subsystem and offers an easy way to launch Windows applications.
+- Microsoft Office links (e.g. ms-word://) from the host system are automatically opened in the Windows subsystem. (Note: You may need to use an [User Agent switcher](https://github.com/ray-lothian/UserAgent-Switcher/) Browser Extension and set the User-Agent to Windows, as as the Office webapps typically hide the "Open in Desktop App" option for Linux users.)
 
 ## Supported Applications
 **WinApps supports <u>*ALL*</u> Windows applications.**
@@ -403,9 +404,18 @@ REMOVABLE_MEDIA="/run/media"
 # [ADDITIONAL FREERDP FLAGS & ARGUMENTS]
 # NOTES:
 # - You can try adding /network:lan to these flags in order to increase performance, however, some users have faced issues with this.
-# DEFAULT VALUE: '/cert:tofu /sound /microphone +home-drive'
+# DEFAULT VALUE: '/cert:tofu /sound /microphone'
 # VALID VALUES: See https://github.com/awakecoding/FreeRDP-Manuals/blob/master/User/FreeRDP-User-Manual.markdown
-RDP_FLAGS="/cert:tofu /sound /microphone +home-drive"
+RDP_FLAGS="/cert:tofu /sound /microphone"
+
+# [MULTIPLE MONITORS]
+# NOTES:
+# - If enabled, a FreeRDP bug *might* produce a black screen.
+# DEFAULT VALUE: 'false'
+# VALID VALUES:
+# - 'true'
+# - 'false'
+MULTIMON="false"
 
 # [DEBUG WINAPPS]
 # NOTES:
@@ -443,6 +453,31 @@ AUTOPAUSE_TIME="300"
 # DEFAULT VALUE: '' (BLANK)
 # VALID VALUES: The command required to run FreeRDPv3 on your system (e.g., 'xfreerdp', 'xfreerdp3', etc.).
 FREERDP_COMMAND=""
+
+# [TIMEOUTS]
+# NOTES:
+# - These settings control various timeout durations within the WinApps setup.
+# - Increasing the timeouts is only necessary if the corresponding errors occur.
+# - Ensure you have followed all the Troubleshooting Tips in the error message first.
+
+# PORT CHECK
+# - The maximum time (in seconds) to wait when checking if the RDP port on Windows is open.
+# - Corresponding error: "NETWORK CONFIGURATION ERROR" (exit status 13).
+# DEFAULT VALUE: '5'
+PORT_TIMEOUT="5"
+
+# RDP CONNECTION TEST
+# - The maximum time (in seconds) to wait when testing the initial RDP connection to Windows.
+# - Corresponding error: "REMOTE DESKTOP PROTOCOL FAILURE" (exit status 14).
+# DEFAULT VALUE: '30'
+RDP_TIMEOUT="30"
+
+# APPLICATION SCAN
+# - The maximum time (in seconds) to wait for the script that scans for installed applications on Windows to complete.
+# - Corresponding error: "APPLICATION QUERY FAILURE" (exit status 15).
+# DEFAULT VALUE: '60'
+APP_SCAN_TIMEOUT="60"
+
 ```
 
 > [!IMPORTANT]
@@ -457,7 +492,7 @@ FREERDP_COMMAND=""
 - For domain users, you can uncomment and change `RDP_DOMAIN`.
 - On high-resolution (UHD) displays, you can set `RDP_SCALE` to the scale you would like to use (100, 140 or 180).
 - To add additional flags to the FreeRDP call (e.g. `/prevent-session-lock 120`), uncomment and use the `RDP_FLAGS` configuration option.
-- For multi-monitor setups, you can try adding `/multimon` to `RDP_FLAGS`. A FreeRDP bug may result in a black screen however, in which case you should revert this change.
+- For multi-monitor setups, you can try enabling `MULTIMON`. A FreeRDP bug may result in a black screen however, in which case you should revert this change.
 - If you enable `DEBUG`, a log will be created on each application start in `~/.local/share/winapps/winapps.log`.
 - If using a system on which the FreeRDP command is not `xfreerdp` or `xfreerdp3`, the correct command can be specified using `FREERDP_COMMAND`.
 
@@ -544,6 +579,11 @@ The installer can be run multiple times. To update your installation of WinApps:
 2. Pull the latest changes from the WinApps GitHub repository.
 3. Re-install WinApps using the WinApps installer by running `winapps-setup`.
 
+## WinApps Launcher (Optional)
+The [WinApps Launcher](https://github.com/winapps-org/winapps-launcher) provides a simple system tray menu that makes it easy to launch your installed Windows applications, open a full desktop RDP session, and control your Windows VM or container. You can start, stop, pause, reboot or hibernate Windows, as well as access your installed applications from a convenient list. This lightweight, optional tool helps streamline your overall WinApps experience.
+
+<img src="./demo/launcher.gif" width=1000 alt="WinApps Launcher Animation.">
+
 ## Installation using Nix
 
 First, follow Step 1 of the normal installation guide to create your VM.

apps/ms-office-protocol-handler.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Name=Microsoft Office Protocol Handler
+Comment=Handle Microsoft Office URI schemes via WinApps
+Exec=winapps manual %u
+Terminal=false
+Type=Application
+MimeType=x-scheme-handler/ms-word;x-scheme-handler/ms-excel;x-scheme-handler/ms-powerpoint;x-scheme-handler/ms-outlook;x-scheme-handler/ms-access;x-scheme-handler/ms-visio;x-scheme-handler/ms-project;x-scheme-handler/ms-teams;x-scheme-handler/ms-whiteboard;x-scheme-handler/ms-officeapp;
+NoDisplay=true
+Categories=Office;Utility;

bin/winapps

@@ -49,7 +49,9 @@ REMOVABLE_MEDIA=""
 RDP_SCALE=100
 AUTOPAUSE="off"
 AUTOPAUSE_TIME="300"
+MULTIMON="false"
 DEBUG="true"
+MULTI_FLAG=""
 
 # OTHER
 FREERDP_PID=-1
@@ -210,6 +212,9 @@ function waLoadConfig() {
         waThrowExit $EC_MISSING_CONFIG
     fi
 
+    # Update 'MULTI_FLAG' based on 'MULTIMON'.
+    MULTI_FLAG=$([[ $MULTIMON == "true" ]] && echo "/multimon" || echo "+span")
+
     # Update $RDP_SCALE.
     waFixScale
     # Update when $REMOVABLE_MEDIA is null
@@ -516,7 +521,11 @@ function waRunCommand() {
             /u:"$RDP_USER" \
             /p:"$RDP_PASS" \
             /scale:"$RDP_SCALE" \
+            +dynamic-resolution \
             +auto-reconnect \
+            +home-drive \
+            +clipboard \
+            -wallpaper \
             /wm-class:"Microsoft Windows" \
             /t:"Windows RDP Session [$RDP_IP]" \
             /v:"$RDP_IP" &>/dev/null &
@@ -531,7 +540,12 @@ function waRunCommand() {
             /u:"$RDP_USER" \
             /p:"$RDP_PASS" \
             /scale:"$RDP_SCALE" \
+            +dynamic-resolution \
             +auto-reconnect \
+            +home-drive \
+            +clipboard \
+            -wallpaper \
+            "$MULTI_FLAG" \
             /app:program:"$2" \
             /v:"$RDP_IP" &>/dev/null &
 
@@ -563,7 +577,12 @@ function waRunCommand() {
                 /u:"$RDP_USER" \
                 /p:"$RDP_PASS" \
                 /scale:"$RDP_SCALE" \
+                +dynamic-resolution \
                 +auto-reconnect \
+                +home-drive \
+                +clipboard \
+                -wallpaper \
+                "$MULTI_FLAG" \
                 /wm-class:"$FULL_NAME" \
                 /app:program:"$WIN_EXECUTABLE",icon:"$ICON",name:"$FULL_NAME" \
                 /v:"$RDP_IP" &>/dev/null &
@@ -584,8 +603,13 @@ function waRunCommand() {
                 /u:"$RDP_USER" \
                 /p:"$RDP_PASS" \
                 /scale:"$RDP_SCALE" \
+                +dynamic-resolution \
                 +auto-reconnect \
+                +home-drive \
+                +clipboard \
                 /drive:media,"$REMOVABLE_MEDIA" \
+                -wallpaper \
+                "$MULTI_FLAG" \
                 /wm-class:"$FULL_NAME" \
                 /app:program:"$WIN_EXECUTABLE",icon:"$ICON",name:$"FULL_NAME",cmd:\""$FILE_PATH"\" \
                 /v:"$RDP_IP" &>/dev/null &

packages/winapps/default.nix

@@ -11,12 +11,12 @@
   ...
 }:
 let
-  rev = "885d02079a36aa9696de46440c5b29b95278f904";
-  hash = "sha256-hkD1siuwlRNOnXpDETZEQlIb/j91hkCspAUl/m5BB6g=";
+  rev = "2b2f4cea698096829fbd1c3c15970034a6f53261";
+  hash = "sha256-km8q3IL5sETbFsscNy4dDxYTytuKPJQJY81p7tSk63A=";
 in
 stdenv.mkDerivation rec {
   pname = "winapps";
-  version = "0-unstable-2025-05-26";
+  version = "0-unstable-2025-06-05";
 
   src = fetchFromGitHub {
     owner = "winapps-org";

setup.sh

@@ -92,8 +92,13 @@ VM_NAME="RDPWindows" # Name of the Windows VM (FOR 'libvirt' ONLY).
 WAFLAVOR="docker"    # Imported variable.
 RDP_SCALE=100        # Imported variable.
 RDP_FLAGS=""         # Imported variable.
+MULTIMON="false"     # Imported variable.
 DEBUG="true"         # Imported variable.
 FREERDP_COMMAND=""   # Imported variable.
+MULTI_FLAG=""        # Set based on value of $MULTIMON.
+PORT_TIMEOUT=5      # Default port check timeout.
+RDP_TIMEOUT=30      # Default RDP connection test timeout.
+APP_SCAN_TIMEOUT=60 # Default application scan timeout.
 
 # PERMISSIONS AND DIRECTORIES
 SUDO=""         # Set to "sudo" if the user specifies '--system', or "" if the user specifies '--user'.
@@ -986,7 +991,7 @@ function waCheckPortOpen() {
     fi
 
     # Check for an open RDP port.
-    if ! timeout 5 nc -z "$RDP_IP" "$RDP_PORT" &>/dev/null; then
+    if ! timeout "$PORT_TIMEOUT" nc -z "$RDP_IP" "$RDP_PORT" &>/dev/null; then
         # Complete the previous line.
         echo -e "${FAIL_TEXT}Failed!${CLEAR_TEXT}\n"
 
@@ -999,6 +1004,7 @@ function waCheckPortOpen() {
         # Display the suggested action(s).
         echo "--------------------------------------------------------------------------------"
         echo "Please ensure Remote Desktop is configured on Windows as per the WinApps README."
+        echo -e "Then you can try increasing the ${COMMAND_TEXT}PORT_TIMEOUT${CLEAR_TEXT} in ${COMMAND_TEXT}${CONFIG_PATH}${CLEAR_TEXT}."
         echo "--------------------------------------------------------------------------------"
 
         # Terminate the script.
@@ -1041,6 +1047,9 @@ function waCheckRDPAccess() {
         /p:"$RDP_PASS" \
         /scale:"$RDP_SCALE" \
         +auto-reconnect \
+        +home-drive \
+        -wallpaper \
+        +dynamic-resolution \
         /app:program:"C:\Windows\System32\cmd.exe",cmd:"/C type NUL > $TEST_PATH_WIN && tsdiscon" \
         /v:"$RDP_IP" &>"$FREERDP_LOG" &
 
@@ -1050,8 +1059,8 @@ function waCheckRDPAccess() {
     # Initialise the time counter.
     ELAPSED_TIME=0
 
-    # Wait a maximum of 30 seconds for the background process to complete.
-    while [ "$ELAPSED_TIME" -lt 30 ]; do
+    # Wait a maximum of $RDP_TIMEOUT seconds for the background process to complete.
+    while [ "$ELAPSED_TIME" -lt "$RDP_TIMEOUT" ]; do
         # Check if the FreeRDP process is complete or if the test file exists.
         if ! ps -p "$FREERDP_PROC" &>/dev/null || [ -f "$TEST_PATH" ]; then
             break
@@ -1086,6 +1095,7 @@ function waCheckRDPAccess() {
         echo "  - Ensure the user is logged out of Windows prior to initiating the WinApps installation."
         echo "  - Ensure the credentials within the WinApps configuration file are correct."
         echo -e "  - Utilise a new certificate by removing relevant certificate(s) in ${COMMAND_TEXT}${HOME}/.config/freerdp/server${CLEAR_TEXT}."
+        echo -e "  - Try increasing the ${COMMAND_TEXT}RDP_TIMEOUT${CLEAR_TEXT} in ${COMMAND_TEXT}${CONFIG_PATH}${CLEAR_TEXT}."
         echo "  - If using 'libvirt', ensure the Windows VM is correctly named as specified within the README."
         echo "  - If using 'libvirt', ensure 'Remote Desktop' is enabled within the Windows VM."
         echo "  - If using 'libvirt', ensure you have merged 'RDPApps.reg' into the Windows VM's registry."
@@ -1132,6 +1142,10 @@ function waFindInstalled() {
         # Extract the name of the application from the absolute path of the folder.
         APPLICATION="$(basename "$APPLICATION")"
 
+        if [[ "$APPLICATION" == "ms-office-protocol-handler.desktop" ]]; then
+            continue
+        fi
+
         # Source 'Info' File Containing:
         # - The Application Name          (FULL_NAME)
         # - The Shortcut Name             (NAME)
@@ -1167,6 +1181,9 @@ function waFindInstalled() {
         /p:"$RDP_PASS" \
         /scale:"$RDP_SCALE" \
         +auto-reconnect \
+        +home-drive \
+        -wallpaper \
+        +dynamic-resolution \
         /app:program:"C:\Windows\System32\cmd.exe",cmd:"/C "$BATCH_SCRIPT_PATH_WIN"" \
         /v:"$RDP_IP" &>"$FREERDP_LOG" &
 
@@ -1176,8 +1193,8 @@ function waFindInstalled() {
     # Initialise the time counter.
     ELAPSED_TIME=0
 
-    # Wait a maximum of 60 seconds for the batch script to finish running.
-    while [ $ELAPSED_TIME -lt 60 ]; do
+    # Wait a maximum of $APP_SCAN_TIMEOUT seconds for the batch script to finish running.
+    while [ $ELAPSED_TIME -lt "$APP_SCAN_TIMEOUT" ]; do
         # Check if the FreeRDP process is complete or if the 'installed' file exists.
         if ! ps -p "$FREERDP_PROC" &>/dev/null || [ -f "$INST_FILE_PATH" ]; then
             break
@@ -1208,6 +1225,7 @@ function waFindInstalled() {
         # Display the suggested action(s).
         echo "--------------------------------------------------------------------------------"
         echo -e "Please view the log at ${COMMAND_TEXT}${FREERDP_LOG}${CLEAR_TEXT}."
+        echo -e "You can try increasing the ${COMMAND_TEXT}APP_SCAN_TIMEOUT${CLEAR_TEXT} in ${COMMAND_TEXT}${CONFIG_PATH}${CLEAR_TEXT}."
         echo "--------------------------------------------------------------------------------"
 
         # Terminate the script.
@@ -1312,9 +1330,9 @@ MimeType=${MIME_TYPES}"
 function waConfigureOfficiallySupported() {
     # Declare variables.
     local OSA_LIST=() # Stores a list of all officially supported applications installed on Windows.
+    local OFFICE_APPS=("access" "access-o365" "access-o365-x86" "access-x86" "adobe-cc" "acrobat9" "acrobat-x-pro" "aftereffects-cc" "audition-cc" "bridge-cc" "bridge-cc-x86" "bridge-cs6" "bridge-cs6-x86" "cmd" "dymo-connect" "excel" "excel-o365" "excel-o365-x86" "excel-x86" "excel-x86-2010" "explorer" "iexplorer" "illustrator-cc" "lightroom-cc" "linqpad8" "mirc" "mspaint" "onenote" "onenote-o365" "onenote-o365-x86" "onenote-x86" "outlook" "outlook-o365" "outlook-o365-x86" "powerpoint" "powerpoint-o365" "powerpoint-o365-x86" "powerpoint-x86" "publisher" "publisher-o365" "publisher-o365-x86" "publisher-x86" "project" "project-x86" "remarkable-desktop" "ssms20" "visual-studio-comm" "visual-studio-ent" "visual-studio-pro" "visio" "visio-x86" "word" "word-o365" "word-o365-x86" "word-x86" "word-x86-2010")
 
     # Read the list of officially supported applications that are installed on Windows into an array, returning an empty array if no such files exist.
-    # This will remove leading and trailing whitespace characters as well as ignore empty lines.
     readarray -t OSA_LIST < <(grep -v '^[[:space:]]*$' "$INST_FILE_PATH" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' 2>/dev/null || true)
 
     # Create application entries for each officially supported application.
@@ -1328,6 +1346,19 @@ function waConfigureOfficiallySupported() {
         # Configure the application.
         waConfigureApp "$OSA" svg
 
+        # Check if the application is an Office app and copy the protocol handler.
+        if [[ " ${OFFICE_APPS[*]} " == *" $OSA "* ]]; then
+            # Determine the target directory based on whether the installation is for the system or user.
+            if [[ "$OPT_SYSTEM" -eq 1 ]]; then
+                TARGET_DIR="$SYS_APP_PATH"
+            else
+                TARGET_DIR="$USER_APP_PATH"
+            fi
+
+            # Copy the protocol handler to the appropriate directory.
+            $SUDO cp "./apps/ms-office-protocol-handler.desktop" "$TARGET_DIR/ms-office-protocol-handler.desktop"
+        fi
+
         # Print feedback.
         echo -e "${DONE_TEXT}Done!${CLEAR_TEXT}"
     done
@@ -1550,6 +1581,13 @@ function waInstall() {
     # Check for missing dependencies.
     waCheckInstallDependencies
 
+    # Update $MULTI_FLAG.
+    if [[ $MULTIMON == "true" ]]; then
+        MULTI_FLAG="/multimon"
+    else
+        MULTI_FLAG="+span"
+    fi
+
     # Update $RDP_SCALE.
     waFixScale
 
@@ -1652,10 +1690,21 @@ function waEnsureOnPath() {
 # Name: 'waUninstall'
 # Role: Uninstalls WinApps.
 function waUninstall() {
+
     # Print feedback.
     [ "$OPT_SYSTEM" -eq 1 ] && echo -e "${BOLD_TEXT}REMOVING SYSTEM INSTALLATION.${CLEAR_TEXT}"
     [ "$OPT_USER" -eq 1 ] && echo -e "${BOLD_TEXT}REMOVING USER INSTALLATION.${CLEAR_TEXT}"
 
+    # Determine the target directory for the protocol handler based on the installation type.
+    if [[ "$OPT_SYSTEM" -eq 1 ]]; then
+        TARGET_DIR="$SYS_APP_PATH"
+    else
+        TARGET_DIR="$USER_APP_PATH"
+    fi
+
+    # Remove the 'ms-office-protocol-handler.desktop' file if it exists.
+    $SUDO rm -f "$TARGET_DIR/ms-office-protocol-handler.desktop"
+
     # Declare variables.
     local WINAPPS_DESKTOP_FILES=()    # Stores a list of '.desktop' file paths.
     local WINAPPS_APP_BASH_SCRIPTS=() # Stores a list of bash script paths.