applyWidgetOutOfTurn method

void applyWidgetOutOfTurn (ParentDataWidget<T> newWidget)

Calls ParentDataWidget.applyParentData on the given widget, passing it the RenderObject whose parent data this element is ultimately responsible for.

This allows a render object's RenderObject.parentData to be modified without triggering a build. This is generally ill-advised, but makes sense in situations such as the following:

  • Build and layout are currently under way, but the ParentData in question does not affect layout, and the value to be applied could not be determined before build and layout (e.g. it depends on the layout of a descendant).

  • Paint is currently under way, but the ParentData in question does not affect layout or paint, and the value to be applied could not be determined before paint (e.g. it depends on the compositing phase).

In either case, the next build is expected to cause this element to be configured with the given new widget (or a widget with equivalent data).

Only ParentDataWidgets that return true for ParentDataWidget.debugCanApplyOutOfTurn can be applied this way.

The new widget must have the same child as the current widget.

An example of when this is used is the AutomaticKeepAlive widget. If it receives a notification during the build of one of its descendants saying that its child must be kept alive, it will apply a KeepAlive widget out of turn. This is safe, because by definition the child is already alive, and therefore this will not change the behavior of the parent this frame. It is more efficient than requesting an additional frame just for the purpose of updating the KeepAlive widget.

Implementation 

void applyWidgetOutOfTurn(ParentDataWidget<T> newWidget) {
  assert(newWidget != null);
  assert(newWidget.debugCanApplyOutOfTurn());
  assert(newWidget.child == widget.child);
  _applyParentData(newWidget);
}