overlay_dismissal.hpp File Reference

The one implementation of Pulp's overlay-dismissal policy. More...

#include <pulp/view/view.hpp>
#include <cstdint>

Go to the source code of this file.

Classes
struct	pulp::view::OverlayPressTarget
struct	pulp::view::OverlayDismissalPolicy
	Tunable defaults for the dismissal policy. More...
struct	pulp::view::PassivePointerRoute
	Where a PASSIVE pointer input — a wheel / two-finger scroll, a trackpad magnify or rotate — at root_pt goes while overlays may be open. More...
struct	pulp::view::ContextPressResult
	What a context (right-button) press resolved to. More...

Namespaces
namespace	pulp
namespace	pulp::view
	Hover-cursor tracking for platform window hosts.

Enumerations
enum class	pulp::view::OverlayPressRouting { pulp::view::no_overlay , pulp::view::routed , pulp::view::not_hittable , pulp::view::dismissed }
	What consulting the generalized overlay slot decided about a press. More...
enum class	pulp::view::OverlayEscapeResult { pulp::view::none , pulp::view::modal , pulp::view::combo_popup , pulp::view::overlay }
	What an Escape keypress dismissed, in the order the policy tries them. More...

Functions
const OverlayDismissalPolicy &	pulp::view::overlay_dismissal_policy ()
	The active policy. Reading is cheap and allocation-free.
void	pulp::view::set_overlay_dismissal_policy (const OverlayDismissalPolicy &policy)
	Replace the active policy. Call from application setup, not mid-gesture.
OverlayPressTarget	pulp::view::route_press_to_active_overlay (View &root, Point root_pt)
	Consult root's generalized overlay slot for a press at root_pt.
View *	pulp::view::hover_target_at (View &root, Point root_pt)
	The view a HOVER at root_pt lands on: the deepest hit inside the topmost open overlay that contains the point, otherwise root.hit_test(root_pt).
PassivePointerRoute	pulp::view::route_passive_pointer (View &root, Point root_pt)
	Resolve a passive pointer input through the root's open overlays.
ContextPressResult	pulp::view::route_context_press (View &root, Point root_pt)
	Route a context (right-button) press at root_pt, consulting the generalized overlay slot first.
OverlayEscapeResult	pulp::view::route_escape_to_active_overlay (View &root, std::uint16_t modifiers=0, bool is_repeat=false)
	Dismiss the topmost thing Escape should close under root.
bool	pulp::view::root_overlay_owns_keyboard (View &root)
	Whether an overlay under root is the kind that should own the keyboard.

Detailed Description

The one implementation of Pulp's overlay-dismissal policy.

Pulp has two independent popup mechanisms that a platform host must keep in step:

A. ComboBox's open native dropdown, a paint-only overlay with no view backing, reached through ComboBox::active_popup_in / close_active_popup / notify_global_click. B. The generalized overlay slot (RootInteractionState::active_overlay), which @pulp/react's <View overlay> prop — and therefore every imported or materialized design's popover — claims via View::claim_overlay().

Deciding what a press or an Escape means for those two lives HERE, not in each host. Hosts own only the native event plumbing and call one verb.

That split is not cosmetic. The policy was previously hand-rolled once per host, and every copy drifted differently: one dismissed another editor's popover because it read the process-global shim mirror instead of the root-owned slot, one never honoured an overlay's outside-click consumption, and the two DAW plugin hosts had no Escape path at all, so a popover opened inside a plugin editor could not be closed from the keyboard. A single implementation is also the only version that is headlessly testable — per-host copies can only be exercised by running a real NSView / HWND / browser.

tools/scripts/overlay_dismissal_wiring_guard.py enforces the arrangement: a host that routes presses must call these verbs, and no host may reach past them to the slot itself.