attachViewHandle method

void attachViewHandle(NutrientViewHandle viewHandle)

Attach the view handle to this controller.

Called by the platform view when it's created. This connects the controller to the underlying native view.

This method is intended for internal SDK use. Users should not call this method directly.

Implementation

void attachViewHandle(NutrientViewHandle viewHandle) {
  _throwIfDisposed();

  // Guard against one controller/adapter instance backing two *live* views at
  // once. The global adapter registered via `Nutrient.initialize` is shared by
  // every `NutrientDocumentView` that doesn't pass its own `adapter:`; because
  // the adapter *is* the controller, two simultaneous views would clobber each
  // other's view handle, document, and event stream.
  //
  // A previously-attached view is still live only if its native instances are
  // still registered — a view unregisters them (via `NutrientViewHandle.dispose`)
  // when torn down. So *sequential* reuse (one view gone before the next
  // attaches) stays allowed; only genuine concurrent reuse trips the guard.
  final previous = _viewHandle;
  if (previous != null &&
      previous.viewId != viewHandle.viewId &&
      NativeInstanceRegistry.hasView(previous.viewId)) {
    final message =
        'This $runtimeType is already driving NutrientDocumentView '
        '#${previous.viewId} and cannot back #${viewHandle.viewId} at the '
        'same time: one adapter/controller instance maps to one live view, '
        'so their native handle, document, and event stream would collide. '
        'Give each NutrientDocumentView its own `adapter:` (allocate it in '
        'the caller and dispose it there, like two_widgets_example) instead '
        'of reusing the global adapter from Nutrient.initialize() for '
        'multiple simultaneous views.';
    // Debug: fail loudly so the collision is caught in development/CI.
    assert(false, message);
    // Release (assert stripped): still surface it so it's diagnosable from
    // logs rather than silently corrupting per-view state.
    debugPrint('[NutrientController] WARNING: $message');
  }

  _viewHandle = viewHandle;
  _viewAttached = true;
}