chromium/ui/views/widget/desktop_aura/README.chromium

This directory contains the views::NativeWidget implementation used for the
Desktop Aura port, and required supporting infrastructure.

Each platform (Windows, macOS, Linux, ChromeOS) has a different window manager.
Each window manager exposes a client-side primitive that represents a window (in
the window management sense). Examples:
  * Windows: HWND
  * macOS: NSWindow
  * ozone/wayland: WaylandWindow

Chromium uses several layers of abstraction on top of these primitives:
  * NativeWindow: A handle to a top-level window. On platforms that run aura
    (Windows, Linux, Lacros, Ash) this is just an aura::Window. Otherwise this
    is a handle to the window-manager client-side primitive mentioned above.
  * NativeView: A handle to a native view. Similar to NativeWindow. Not all
    window managers distinguish between View and Window.
  * AcceleratedWidget: This is a handle to a client-side primitive that is
    responsible for putting pixels onto the screen.
    * Windows: HWND.
    * macOS: A uint64_t that gets mapped to an AcceleratedWidgetMac, a subclass
      of CALayerFrameSink.
    * ozone/wayland: A uint32_t that gets mapped to a WaylandWindow.
  * Widget: Used to bridge between views and NativeView/NativeWindow. Represents
    the views side of the bridge.
  * NativeWidget: Widget's implementation largely delegates to NativeWidget,
    which provides a custom implementation per platform. Some implementation
    (Windows, Linux) may use different NativeWidget implementations for widgets
    backed by an AcceleratedWidget vs those that aren't.

Moving onto aura-specific concepts:
  * aura::Window: A cross-platform abstraction that replaces the NativeWindow.
    Forms a tree hierarchy. An aura::Window is effectively an abstraction over a
    ui::Layer that handles events as an EventTarget.
  * WindowTreeHost: Provides the root aura::Window. WindowTreeHost owns a
    compositor that ultimately enables rendering the contents of an aura::Window
    tree on to an AcceleratedWidget.
  * DesktopWindowTreeHost: A views-specific extension of WindowTreeHost.
  * DesktopNativeWidgetAura: A views-specific implementation of NativeWidget.
    This owns a WindowTreeHost. This owns a |content_window_| which is added as
    a child to the WindowTreeHost's root window. This |content_window_| is the
    NativeView.

Some implications:
  * DesktopWindowTreeHost::IsActive() will return true if any window in the
    hierarchy it hosts is active.
  * DesktopNativeWidgetAura::IsActive() will return true only if the
    |content_window_| is active.
For example: if we display a popup (child aura::Window), then
DesktopWindowTreeHost::IsActive() will return true whereas
DesktopNativeWidgetAura::IsActive() will return false.