diff --git a/packages/flutter/lib/src/foundation/serialization.dart b/packages/flutter/lib/src/foundation/serialization.dart index 5992f00378..753de146e7 100644 --- a/packages/flutter/lib/src/foundation/serialization.dart +++ b/packages/flutter/lib/src/foundation/serialization.dart @@ -13,6 +13,7 @@ import 'package:typed_data/typed_buffers.dart' show Uint8Buffer; /// /// The byte order used is [Endianness.HOST_ENDIAN] throughout. class WriteBuffer { + /// Creates an interface for incrementally building a [ByteData] instance. WriteBuffer() { _buffer = new Uint8Buffer(); _eightBytes = new ByteData(8); @@ -23,49 +24,59 @@ class WriteBuffer { ByteData _eightBytes; Uint8List _eightBytesAsList; + /// Write a Uint8 into the buffer. void putUint8(int byte) { _buffer.add(byte); } + /// Write a Uint16 into the buffer. void putUint16(int value) { _eightBytes.setUint16(0, value, Endianness.HOST_ENDIAN); _buffer.addAll(_eightBytesAsList, 0, 2); } + /// Write a Uint32 into the buffer. void putUint32(int value) { _eightBytes.setUint32(0, value, Endianness.HOST_ENDIAN); _buffer.addAll(_eightBytesAsList, 0, 4); } + /// Write an Int32 into the buffer. void putInt32(int value) { _eightBytes.setInt32(0, value, Endianness.HOST_ENDIAN); _buffer.addAll(_eightBytesAsList, 0, 4); } + /// Write an Int64 into the buffer. void putInt64(int value) { _eightBytes.setInt64(0, value, Endianness.HOST_ENDIAN); _buffer.addAll(_eightBytesAsList, 0, 8); } + /// Write an Float64 into the buffer. void putFloat64(double value) { _eightBytes.setFloat64(0, value, Endianness.HOST_ENDIAN); _buffer.addAll(_eightBytesAsList); } + /// Write all the values from a [Uint8List] into the buffer. void putUint8List(Uint8List list) { _buffer.addAll(list); } + /// Write all the values from a [Int32List] into the buffer. void putInt32List(Int32List list) { _alignTo(4); _buffer.addAll(list.buffer.asUint8List(list.offsetInBytes, 4 * list.length)); } + /// Write all the values from an [Int64List] into the buffer. void putInt64List(Int64List list) { _alignTo(8); _buffer.addAll(list.buffer.asUint8List(list.offsetInBytes, 8 * list.length)); } + /// Write all the values from a [Float64List] into the buffer. void putFloat64List(Float64List list) { _alignTo(8); _buffer.addAll(list.buffer.asUint8List(list.offsetInBytes, 8 * list.length)); @@ -79,6 +90,7 @@ class WriteBuffer { } } + /// Finalize and return the written [ByteData]. ByteData done() { final ByteData result = _buffer.buffer.asByteData(0, _buffer.lengthInBytes); _buffer = null; @@ -90,80 +102,94 @@ class WriteBuffer { /// /// The byte order used is [Endianness.HOST_ENDIAN] throughout. class ReadBuffer { - final ByteData data; - int position = 0; - /// Creates a [ReadBuffer] for reading from the specified [data]. ReadBuffer(this.data) { assert(data != null); } + /// The underlying data being read. + final ByteData data; + + /// The position to read next. + int _position = 0; + + /// Whether the buffer has data remaining to read. + bool get hasRemaining => _position < data.lengthInBytes; + + /// Reads a Uint8 from the buffer. int getUint8() { - return data.getUint8(position++); + return data.getUint8(_position++); } + /// Reads a Uint16 from the buffer. int getUint16() { - final int value = data.getUint16(position, Endianness.HOST_ENDIAN); - position += 2; + final int value = data.getUint16(_position, Endianness.HOST_ENDIAN); + _position += 2; return value; } + /// Reads a Uint32 from the buffer. int getUint32() { - final int value = data.getUint32(position, Endianness.HOST_ENDIAN); - position += 4; + final int value = data.getUint32(_position, Endianness.HOST_ENDIAN); + _position += 4; return value; } + /// Reads an Int32 from the buffer. int getInt32() { - final int value = data.getInt32(position, Endianness.HOST_ENDIAN); - position += 4; + final int value = data.getInt32(_position, Endianness.HOST_ENDIAN); + _position += 4; return value; } + /// Reads an Int64 from the buffer. int getInt64() { - final int value = data.getInt64(position, Endianness.HOST_ENDIAN); - position += 8; + final int value = data.getInt64(_position, Endianness.HOST_ENDIAN); + _position += 8; return value; } + /// Reads a Float64 from the buffer. double getFloat64() { - final double value = data.getFloat64(position, Endianness.HOST_ENDIAN); - position += 8; + final double value = data.getFloat64(_position, Endianness.HOST_ENDIAN); + _position += 8; return value; } + /// Reads the given number of Uint8s from the buffer. Uint8List getUint8List(int length) { - final Uint8List list = data.buffer.asUint8List(data.offsetInBytes + position, length); - position += length; + final Uint8List list = data.buffer.asUint8List(data.offsetInBytes + _position, length); + _position += length; return list; } + /// Reads the given number of Int32s from the buffer. Int32List getInt32List(int length) { _alignTo(4); - final Int32List list = data.buffer.asInt32List(data.offsetInBytes + position, length); - position += 4 * length; + final Int32List list = data.buffer.asInt32List(data.offsetInBytes + _position, length); + _position += 4 * length; return list; } + /// Reads the given number of Int64s from the buffer. Int64List getInt64List(int length) { _alignTo(8); - final Int64List list = data.buffer.asInt64List(data.offsetInBytes + position, length); - position += 8 * length; + final Int64List list = data.buffer.asInt64List(data.offsetInBytes + _position, length); + _position += 8 * length; return list; } + /// Reads the given number of Float64s from the buffer. Float64List getFloat64List(int length) { _alignTo(8); - final Float64List list = data.buffer.asFloat64List(data.offsetInBytes + position, length); - position += 8 * length; + final Float64List list = data.buffer.asFloat64List(data.offsetInBytes + _position, length); + _position += 8 * length; return list; } void _alignTo(int alignment) { - final int mod = position % alignment; + final int mod = _position % alignment; if (mod != 0) - position += alignment - mod; + _position += alignment - mod; } - - bool get hasRemaining => position < data.lengthInBytes; } diff --git a/packages/flutter/lib/src/rendering/layer.dart b/packages/flutter/lib/src/rendering/layer.dart index db69b3d53c..66a79af4bc 100644 --- a/packages/flutter/lib/src/rendering/layer.dart +++ b/packages/flutter/lib/src/rendering/layer.dart @@ -522,7 +522,16 @@ class BackdropFilterLayer extends ContainerLayer { } } +/// A composited layer that uses a physical model to producing lighting effects. +/// +/// For example, the layer casts a shadow according to its geometry and the +/// relative position of lights and other physically modelled objects in the +/// scene. class PhysicalModelLayer extends ContainerLayer { + /// Creates a composited layer that uses a physical model to producing + /// lighting effects. + /// + /// The [clipRRect], [elevation], and [color] arguments must not be null. PhysicalModelLayer({ @required this.clipRRect, @required this.elevation, diff --git a/packages/flutter/lib/src/services/message_codecs.dart b/packages/flutter/lib/src/services/message_codecs.dart index 640aa16977..8e1e2be186 100644 --- a/packages/flutter/lib/src/services/message_codecs.dart +++ b/packages/flutter/lib/src/services/message_codecs.dart @@ -11,6 +11,8 @@ import 'message_codec.dart'; /// [MessageCodec] with unencoded binary messages represented using [ByteData]. class BinaryCodec implements MessageCodec { + /// Creates a [MessageCodec] with unencoded binary messages represented using + /// [ByteData]. const BinaryCodec(); @override @@ -22,6 +24,7 @@ class BinaryCodec implements MessageCodec { /// [MessageCodec] with UTF-8 encoded String messages. class StringCodec implements MessageCodec { + /// Creates a [MessageCodec] with UTF-8 encoded String messages. const StringCodec(); @override @@ -54,6 +57,8 @@ class JSONMessageCodec implements MessageCodec { // The codec serializes messages as defined by the JSON codec of the // dart:convert package. The format used must match the Android and // iOS counterparts. + + /// Creates a [MessageCodec] with UTF-8 encoded JSON messages. const JSONMessageCodec(); @override @@ -72,6 +77,7 @@ class JSONMessageCodec implements MessageCodec { } /// [MethodCodec] with UTF-8 encoded JSON method calls and result envelopes. +/// /// Values supported as method arguments and result payloads are those supported /// by [JSONMessageCodec]. class JSONMethodCodec implements MethodCodec { @@ -87,6 +93,9 @@ class JSONMethodCodec implements MethodCodec { // element, or // * three-element lists containing, in order, an error code String, an // error message String, and an error details value. + + /// Creates a [MethodCodec] with UTF-8 encoded JSON method calls and result + /// envelopes. const JSONMethodCodec(); @override @@ -185,6 +194,7 @@ class StandardMessageCodec implements MessageCodec { static const int _kList = 12; static const int _kMap = 13; + /// Creates a [MessageCodec] using the Flutter standard binary encoding. const StandardMessageCodec(); @override @@ -379,6 +389,7 @@ class StandardMethodCodec implements MethodCodec { // * In the error case, the concatenation of the encoding of the error code // string, the error message string, and the error details value. + /// Creates a [MethodCodec] using the Flutter standard binary encoding. const StandardMethodCodec(); @override diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 867d98b1bb..644d8122dd 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -2563,9 +2563,7 @@ abstract class Element implements BuildContext { if (_dirty) owner.scheduleBuildFor(this); if (hadDependencies) - didChangeDependencies - - (); + didChangeDependencies(); } /// Transition from the "active" to the "inactive" lifecycle state. @@ -3047,9 +3045,9 @@ abstract class ComponentElement extends Element { rebuild(); } - /// Calls the `build` method of the [StatelessWidget] object (for - /// stateless widgets) or the [State] object (for stateful widgets) and - /// then updates the widget tree. + /// Calls the [StatelessWidget.build] method of the [StatelessWidget] object + /// (for stateless widgets) or the [State.build] method of the [State] object + /// (for stateful widgets) and then updates the widget tree. /// /// Called automatically during [mount] to generate the first build, and by /// [rebuild] when the element needs updating. @@ -3091,6 +3089,9 @@ abstract class ComponentElement extends Element { }); } + /// Subclasses should override this function to actually call the appropriate + /// `build` function (e.g., [StatelessWidget.build] or [State.build]) for + /// their widget. @protected Widget build(); diff --git a/packages/flutter/lib/src/widgets/heroes.dart b/packages/flutter/lib/src/widgets/heroes.dart index 6e9531b01a..66b7a66b42 100644 --- a/packages/flutter/lib/src/widgets/heroes.dart +++ b/packages/flutter/lib/src/widgets/heroes.dart @@ -416,10 +416,13 @@ class _HeroFlight { class HeroController extends NavigatorObserver { /// Creates a hero controller with the given [RectTween] constructor if any. /// - /// The [createRectTween] argument is optional. If null, a linear - /// [RectTween] is used. + /// The [createRectTween] argument is optional. If null, the controller uses a + /// linear [RectTween]. HeroController({ this.createRectTween }); + /// Used to create [RectTween]s that interpolate the position of heros in flight. + /// + /// If null, the controller uses a linear [RectTween]. final CreateRectTween createRectTween; // Disable Hero animations while a user gesture is controlling the navigation. diff --git a/packages/flutter/lib/src/widgets/pages.dart b/packages/flutter/lib/src/widgets/pages.dart index 245da30f8d..db9467db3f 100644 --- a/packages/flutter/lib/src/widgets/pages.dart +++ b/packages/flutter/lib/src/widgets/pages.dart @@ -62,6 +62,10 @@ Widget _defaultTransitionsBuilder(BuildContext context, Animation animat /// Callers must define the [pageBuilder] function which creates the route's /// primary contents. To add transitions define the [transitionsBuilder] function. class PageRouteBuilder extends PageRoute { + /// Creates a route that deletates to builder callbacks. + /// + /// The [pageBuilder], [transitionsBuilder], [opaque], [barrierDismissable], + /// and [maintainState] arguments must not be null. PageRouteBuilder({ RouteSettings settings: const RouteSettings(), this.pageBuilder, @@ -79,7 +83,14 @@ class PageRouteBuilder extends PageRoute { assert(maintainState != null); } + /// Used build the route's primary contents. + /// + /// See [ModalRoute.buildPage] for complete definition of the parameters. final RoutePageBuilder pageBuilder; + + /// Used to build the route's transitions. + /// + /// See [ModalRoute.buildTransitions] for complete definition of the parameters. final RouteTransitionsBuilder transitionsBuilder; @override diff --git a/packages/flutter/lib/src/widgets/text_selection.dart b/packages/flutter/lib/src/widgets/text_selection.dart index c3e068c395..42280582b4 100644 --- a/packages/flutter/lib/src/widgets/text_selection.dart +++ b/packages/flutter/lib/src/widgets/text_selection.dart @@ -63,8 +63,8 @@ abstract class TextSelectionDelegate { void hideToolbar(); } -// An interface for building the selection UI, to be provided by the -// implementor of the toolbar widget. +/// An interface for building the selection UI, to be provided by the +/// implementor of the toolbar widget. abstract class TextSelectionControls { /// Builds a selection handle of the given type. Widget buildHandle(BuildContext context, TextSelectionHandleType type);