Fix: Prevent background apps from stealing keyboard focus

[PrayagCodes]

Summary

Fixes a bug where background applications steal keyboard focus from the currently active window (e.g., terminal) when launched or during drag-and-drop operations.

Problem

When background applications are launched, they incorrectly receive keyboard focus, interrupting the user's workflow. This is especially problematic when:

• A user is typing in a terminal
• A background app launches automatically
• The terminal loses focus, disrupting the user's input

Root Cause

The UIWindow component was calling focusWindow() unconditionally in several places:

1. During initial window creation when is_visible was true
2. When items were dropped on the window
3. When items were dragged over the window (after a timeout)

Background apps should not receive focus, but the component had no mechanism to distinguish them from regular apps.

Impact

• Keyboard focus stolen from active windows when background apps launch
• Disrupted user workflow, especially when typing in terminals
• Poor user experience for apps that run in the background

Solution

Implemented a component-level solution that adds an options.background property to the UIWindow component, which prevents focus operations when set to true.

Changes Made

1. Add options.background Property

Location: src/gui/src/UI/UIWindow.js

Add a new options.background property to the UIWindow component, which defaults to false.

options.background = options.background ?? false;

2. Modify Initial Window Creation Logic

Location: src/gui/src/UI/UIWindow.js

Modify the initial window creation logic to only call focusWindow() if the options.background property is false.

Before:

if ( options.is_visible ) {
    $(el_window).focusWindow();
}

After:

if ( options.is_visible && !options.background ) {
    $(el_window).focusWindow();
}

3. Update Event Handlers

Location: src/gui/src/UI/UIWindow.js

Update two additional event handlers to also respect the options.background flag:

A. Drop Event Handler

When items are dropped on the window, only focus if not a background app:

// In the drop handler
if ( !options.background ) {
    $(el_window).focusWindow();
}

B. Dragster Enter Event Handler

When items are dragged over the window, only set focus timeout if not a background app:

// In dragster enter handler
if ( !options.background ) {
    drag_enter_timeout = setTimeout(function(){
        $(el_window).focusWindow();
    }, 1400);
}

Testing

Manual Testing

Verified the following scenarios:

1. Launch a background app (with background: true)

   • ✅ Window does not receive focus at creation
   • ✅ Currently active window (terminal) maintains focus

2. Drag items over a background app window

   • ✅ Focus is not stolen during drag operations
   • ✅ Timeout for focus is not set

3. Drop items on a background app window

   • ✅ Focus is not stolen on drop
   • ✅ Currently active window maintains focus

4. Launch a regular app (with background: false or undefined)

   • ✅ Window receives focus as expected
   • ✅ Normal behavior is preserved

Acceptance Criteria

• ✅ Background apps do not receive focus at window creation
• ✅ Background apps do not steal focus during drag-and-drop operations
• ✅ Regular apps continue to receive focus as expected
• ✅ Currently active windows maintain focus when background apps launch
• ✅ No regression in normal app launching behavior

Related Files

• src/gui/src/UI/UIWindow.js - Main implementation
• src/gui/src/helpers/launch_app.js - Passes background flag to UIWindow

Breaking Changes

None. This is a bug fix that maintains backward compatibility. Regular apps (without background: true) continue to behave exactly as before.