diff --git a/packages/flutter/lib/src/foundation/binding.dart b/packages/flutter/lib/src/foundation/binding.dart index bdaa05fdd6b..1b4f180b879 100644 --- a/packages/flutter/lib/src/foundation/binding.dart +++ b/packages/flutter/lib/src/foundation/binding.dart @@ -189,7 +189,7 @@ abstract class BindingBase { assert(!locked); } - /// Cause the entire application to redraw. + /// Cause the entire application to redraw, e.g. after a hot reload. /// /// This is used by development tools when the application code has changed, /// to cause the application to pick up any changed code. It can be triggered @@ -212,7 +212,7 @@ abstract class BindingBase { } /// This method is called by [reassembleApplication] to actually cause the - /// application to reassemble. + /// application to reassemble, e.g. after a hot reload. /// /// Bindings are expected to use this method to reregister anything that uses /// closures, so that they do not keep pointing to old code, and to flush any diff --git a/packages/flutter/lib/src/rendering/object.dart b/packages/flutter/lib/src/rendering/object.dart index e4d6fdc0a2e..345ed92f1f8 100644 --- a/packages/flutter/lib/src/rendering/object.dart +++ b/packages/flutter/lib/src/rendering/object.dart @@ -997,10 +997,14 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im } /// Cause the entire subtree rooted at the given [RenderObject] to be marked - /// dirty for layout, paint, etc. This is called by the [RendererBinding] in - /// response to the `ext.flutter.reassemble` hook, which is used by - /// development tools when the application code has changed, to cause the - /// widget tree to pick up any changed implementations. + /// dirty for layout, paint, etc, so that the effects of a hot reload can be + /// seen, or so that the effect of changing a global debug flag (such as + /// [debugPaintSizeEnabled]) can be applied. + /// + /// This is called by the [RendererBinding] in response to the + /// `ext.flutter.reassemble` hook, which is used by development tools when the + /// application code has changed, to cause the widget tree to pick up any + /// changed implementations. /// /// This is expensive and should not be called except during development. /// diff --git a/packages/flutter/lib/src/services/text_input.dart b/packages/flutter/lib/src/services/text_input.dart index 5b6b75a68a2..c90ef16756d 100644 --- a/packages/flutter/lib/src/services/text_input.dart +++ b/packages/flutter/lib/src/services/text_input.dart @@ -244,7 +244,7 @@ abstract class TextInputClient { void performAction(TextInputAction action); } -/// A interface for interacting with a text input control. +/// An interface for interacting with a text input control. /// /// See also: /// diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 70ada7b363e..c3e6691e782 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -857,6 +857,10 @@ typedef void StateSetter(VoidCallback fn); /// associated widget (e.g., to start implicit animations). The framework /// always calls [build] after calling [didUpdateWidget], which means any /// calls to [setState] in [didUpdateWidget] are redundant. +/// * During development, if a hot reload occurs (whether initiated from the +/// command line `flutter` tool by pressing `r`, or from an IDE), the +/// [reassemble] method is called. This provides an opportunity to +/// reinitialize any data that was prepared in the [initState] method. /// * If the subtree containing the [State] object is removed from the tree /// (e.g., because the parent built a widget with a different [runtimeType] /// or [Widget.key]), the framework calls the [deactivate] method. Subclasses @@ -994,7 +998,8 @@ abstract class State extends Diagnosticable { @protected void didUpdateWidget(covariant T oldWidget) { } - /// Called whenever the application is reassembled during debugging. + /// Called whenever the application is reassembled during debugging, for + /// example during hot reload. /// /// This method should rerun any initialization logic that depends on global /// state, for example, image loading from asset bundles (since the asset @@ -2001,7 +2006,7 @@ abstract class BuildContext { /// This class tracks which widgets need rebuilding, and handles other tasks /// that apply to widget trees as a whole, such as managing the inactive element /// list for the tree and triggering the "reassemble" command when necessary -/// during debugging. +/// during hot reload when debugging. /// /// The main build owner is typically owned by the [WidgetsBinding], and is /// driven from the operating system along with the rest of the @@ -2365,7 +2370,8 @@ class BuildOwner { /// Cause the entire subtree rooted at the given [Element] to be entirely /// rebuilt. This is used by development tools when the application code has - /// changed, to cause the widget tree to pick up any changed implementations. + /// changed and is being hot-reloaded, to cause the widget tree to pick up any + /// changed implementations. /// /// This is expensive and should not be called except during development. void reassemble(Element root) { diff --git a/packages/flutter/lib/src/widgets/routes.dart b/packages/flutter/lib/src/widgets/routes.dart index 271b173bc45..54aad87510a 100644 --- a/packages/flutter/lib/src/widgets/routes.dart +++ b/packages/flutter/lib/src/widgets/routes.dart @@ -1114,7 +1114,6 @@ abstract class PopupRoute extends ModalRoute { /// Widget build(BuildContext context) => new Container(); /// /// } -/// /// ``` class RouteObserver> extends NavigatorObserver { final Map _listeners = {}; @@ -1157,7 +1156,10 @@ class RouteObserver> extends NavigatorObserver { } } -/// A interface that is aware of its current Route. +/// An interface for objects that are aware of their current [Route]. +/// +/// This is used with [RouteObserver] to make a widget aware of changes to the +/// [Navigator]'s session history. abstract class RouteAware { /// Called when the top route has been popped off, and the current route /// shows up. diff --git a/packages/flutter/lib/src/widgets/text_selection.dart b/packages/flutter/lib/src/widgets/text_selection.dart index 93b1071c940..ce54a8e8cf3 100644 --- a/packages/flutter/lib/src/widgets/text_selection.dart +++ b/packages/flutter/lib/src/widgets/text_selection.dart @@ -21,15 +21,23 @@ import 'transitions.dart'; /// /// With mixed-direction text, both handles may be the same type. Examples: /// -/// * LTR text: 'the fox': -/// The '<' is drawn with the [left] type, the '>' with the [right] +/// * LTR text: 'the <quick brown> fox': +/// +/// The '<' is drawn with the [left] type, the '>' with the [right] +/// +/// * RTL text: 'XOF <NWORB KCIUQ> EHT': /// -/// * RTL text: 'xof eht': /// Same as above. /// -/// * mixed text: '