Desktop windowing

This page details features and testing scenarios related to desktop windowing.

Desktop features

This section describes key features and configurations related to desktop windowing.

Enable task limits

To configure the maximum number of tasks supported in desktop windowing:

  1. Enable desktop windowing.

  2. Set the config overlay flag config_maxDesktopWindowingActiveTasks in config.xml to the maximum number of supported tasks. To support an unlimited number of tasks, set the flag to the default value of 0:

    <integer name="config_maxDesktopWindowingActiveTasks">4</integer>

Browser-specific features

Android 16 introduced two browser-specific features: customizable header insets and app instance management. This section describes the testing scenarios to verify browser compatibility. OEMs must verify that the feature implementation works as intended.

Test cases for customizable header insets

The following test cases verify browser compatibility with customizable header insets:

  • UI interactivity: Verify that the browser's caption bar UI remains fully interactive across all windowing configurations (freeform, split screen, and fullscreen).
  • System icon clearance: Confirm that the browser UI doesn't draw under system icons.
  • Foreground color application: Verify that the correct foreground colors are applied to system icons on the app header based on the browser's theme. This is particularly important when the browser's theme differs from the system theme.
  • Window dragging: Validate that a freeform window can be dragged by long-pressing anywhere on an empty area of the tab strip.
  • Tab visibility on resize: Test that tabs are shown or hidden based on the window's width to maintain optimal usability.

Test cases for app instance management with draggable gesture behavior

The following test cases verify browser compatibility with app instance management:

  • New window creation: Confirm that dragging a tab from the tab strip to an empty area creates a new browser window containing that tab.
  • No new window for the last tab (single instance): If only one browser instance is open, verify that dragging the last tab in that window doesn't create a new window.

Desktop-first and touch-first behavioral modes

Desktop windowing is designed to support a variety of form factors beyond standalone tablets, including clamshells, and devices with connected external displays. Because different form factors carry different user expectations for interaction, often dictated by the primary input method (touch or keyboard and mouse), desktop windowing employs two distinct behavioral modes:

  • Desktop-first mode: Provides a keyboard and touchpad-optimized experience where the system prefers freeform windowing. This mode is intended for laptop-like configurations.
  • Touch-first mode: Provides a touch-optimized experience where the system prefers full screen windowing. This mode is the default for standalone tablets.

These modes are not separate desktop environments but rather per-display states that dictate default UI behaviors.

Behavioral differences

The following table summarizes the key UI and functional differences between the desktop-first and touch-first modes:

Feature Touch-first Mode Desktop-first Mode
Default Launch Windows launch in fullscreen unless a freeform window is already on top. Windows launch in freeform unless a fullscreen window is already on top.
Taskbar Type Uses Transient Taskbar (showing only pinned apps) in fullscreen. Always uses Desktop Taskbar (showing pinned and open apps).
Refocusing Windows reactivate based on the current display mode (for example, reactivating in freeform if the display is in desktop windowing). Windows reactivate based on their own saved windowing mode (for example, a fullscreen window always resumes in fullscreen).
Drag-to-Top Dragging a window to the top edge enters Fullscreen. Dragging a window to the top edge enters Maximized state.
Window Controls Uses the app handle for fullscreen controls. Uses the hover menu for fullscreen controls.

The desktop-first mode is a per-display state, meaning a device can simultaneously host a touch-first internal display and a desktop-first external display.

Switching triggers

The system evaluates several factors to determine the appropriate mode for a display:

  • Input peripheral: A display switches to desktop-first if both a keyboard and a touchpad or mouse are connected and enabled.
  • External display: Connected external displays typically default to a desktop-first mode unless they are mirroring the internal display.
  • Device posture: For convertible devices, the mode can switch based on physical orientation (for example, switching to touch-first when the keyboard is flipped back).

Technical Implementation

The "source of truth" for this state is the display windowing mode, specifically the windowing mode of the TaskDisplayArea of the display. Shell and Launcher components can access this state through DisplayAreaInfo or the WindowConfiguration of the display context.