addToHitGrid method

void addToHitGrid(
  1. Pointer<RendererHandle> renderer,
  2. int x,
  3. int y,
  4. int width,
  5. int height,
  6. int id,
)

Registers a rectangular region in OpenTUI's low-level hit grid.

This is a native/debug primitive. Built-in widgets route pointer events through render-tree hit testing and MouseEvent.localPosition, not this ID grid. Keep this available for direct OpenTUI experiments, diagnostics, and parity checks against the native API.

Performance: O(1) per region - very fast registration. Hit testing lookup is O(log n) where n is the number of regions.

Example:

// Register a debug overlay region.
renderer.addToHitGrid(10, 5, 15, 3, debugOverlayId);

final hitId = renderer.checkHit(mouseX, mouseY);
debugLog('native hit grid returned $hitId');

Parameters:

  • renderer: The renderer to add the hit region to
  • x: Left edge column position (0-based)
  • y: Top edge row position (0-based)
  • width: Region width in columns
  • height: Region height in rows
  • id: Unique identifier for this low-level region

IDs should be unique within the current hit grid. Overlapping regions may return the most recently added ID.

Throws FFIException if the underlying C function fails.

See also:

Implementation

void addToHitGrid(
  Pointer<RendererHandle> renderer,
  int x,
  int y,
  int width,
  int height,
  int id,
) {
  _guard('Failed to add to hit grid', () {
    _generated.addToHitGrid(renderer.cast(), x, y, width, height, id);
  });
}