checkHit method

int checkHit(
  1. Pointer<RendererHandle> renderer,
  2. int x,
  3. int y
)

Queries OpenTUI's low-level hit grid at the specified coordinates.

Returns the ID of a region registered with addToHitGrid, or 0 if no region was hit. This is a native/debug primitive; built-in widgets use render-tree hit testing for pointer dispatch.

Performance: O(log n) where n is the number of registered regions. Very fast even with hundreds of interactive elements.

Example:

// Query a region previously registered for native parity debugging.
final hitId = renderer.checkHit(mouseX, mouseY);
debugLog('native hit grid returned $hitId');

Parameters:

  • renderer: The renderer to test coordinates against
  • x: Column position to test (0-based)
  • y: Row position to test (0-based)

Returns:

  • The registered native/debug region ID, or 0 if no region contains the coordinates

Coordinates outside the terminal bounds always return 0. When multiple regions overlap, the most recently added region's ID is returned.

Throws FFIException if the underlying C function fails.

See also:

Implementation

int checkHit(Pointer<RendererHandle> renderer, int x, int y) => _guard(
  'Failed to check hit',
  () => _generated.checkHit(renderer.cast(), x, y),
);