Add some more documentation. (#14717)
diff --git a/packages/flutter/lib/src/cupertino/picker.dart b/packages/flutter/lib/src/cupertino/picker.dart
index 2f18d6f..69ae7ed 100644
--- a/packages/flutter/lib/src/cupertino/picker.dart
+++ b/packages/flutter/lib/src/cupertino/picker.dart
@@ -29,6 +29,14 @@
/// the iOS design specific chrome.
/// * <https://developer.apple.com/ios/human-interface-guidelines/controls/pickers/>
class CupertinoPicker extends StatefulWidget {
+ /// Creates a control used for selecting values.
+ ///
+ /// The [diameterRatio] and [itemExtent] arguments must not be null. The
+ /// [itemExtent] must be greater than zero.
+ ///
+ /// The [backgroundColor] defaults to light gray. It can be set to null to
+ /// disable the background painting entirely; this is mildly more efficient
+ /// than using [Colors.transparent].
const CupertinoPicker({
Key key,
this.diameterRatio: _kDefaultDiameterRatio,
@@ -55,6 +63,9 @@
/// Background color behind the children.
///
/// Defaults to a gray color in the iOS color palette.
+ ///
+ /// This can be set to null to disable the background painting entirely; this
+ /// is mildly more efficient than using [Colors.transparent].
final Color backgroundColor;
/// A [FixedExtentScrollController] to read and control the current item.
@@ -164,26 +175,30 @@
@override
Widget build(BuildContext context) {
- return new DecoratedBox(
- decoration: new BoxDecoration(
- color: widget.backgroundColor,
- ),
- child: new Stack(
- children: <Widget>[
- new Positioned.fill(
- child: new ListWheelScrollView(
- controller: widget.scrollController,
- physics: const FixedExtentScrollPhysics(),
- diameterRatio: widget.diameterRatio,
- itemExtent: widget.itemExtent,
- onSelectedItemChanged: _handleSelectedItemChanged,
- children: widget.children,
- ),
+ Widget result = new Stack(
+ children: <Widget>[
+ new Positioned.fill(
+ child: new ListWheelScrollView(
+ controller: widget.scrollController,
+ physics: const FixedExtentScrollPhysics(),
+ diameterRatio: widget.diameterRatio,
+ itemExtent: widget.itemExtent,
+ onSelectedItemChanged: _handleSelectedItemChanged,
+ children: widget.children,
),
- _buildGradientScreen(),
- _buildMagnifierScreen(),
- ],
- ),
+ ),
+ _buildGradientScreen(),
+ _buildMagnifierScreen(),
+ ],
);
+ if (widget.backgroundColor != null) {
+ result = new DecoratedBox(
+ decoration: new BoxDecoration(
+ color: widget.backgroundColor,
+ ),
+ child: result,
+ );
+ }
+ return result;
}
}
diff --git a/packages/flutter/lib/src/material/scaffold.dart b/packages/flutter/lib/src/material/scaffold.dart
index d1f0942..1c977e5 100644
--- a/packages/flutter/lib/src/material/scaffold.dart
+++ b/packages/flutter/lib/src/material/scaffold.dart
@@ -37,12 +37,13 @@
statusBar,
}
-/// Geometry information for scaffold components.
+/// Geometry information for [Scaffold] components.
///
-/// To get a [ValueNotifier] for the scaffold geometry call
-/// [Scaffold.geometryOf].
+/// To get a [ValueNotifier] for the scaffold geometry of a given
+/// [BuildContext], use [Scaffold.geometryOf].
@immutable
class ScaffoldGeometry {
+ /// Create an object that describes the geometry of a [Scaffold].
const ScaffoldGeometry({
this.bottomNavigationBarTop,
this.floatingActionButtonArea,
diff --git a/packages/flutter/lib/src/semantics/semantics.dart b/packages/flutter/lib/src/semantics/semantics.dart
index 079740d..c078a53 100644
--- a/packages/flutter/lib/src/semantics/semantics.dart
+++ b/packages/flutter/lib/src/semantics/semantics.dart
@@ -1076,8 +1076,8 @@
/// platform's accessibility services (e.g. VoiceOver on iOS and TalkBack on
/// Android). This is used to determine the [nextNodeId] and [previousNodeId]
/// during a semantics update.
- SemanticsSortOrder _sortOrder;
SemanticsSortOrder get sortOrder => _sortOrder;
+ SemanticsSortOrder _sortOrder;
/// The ID of the next node in the traversal order after this node.
///
@@ -1089,6 +1089,7 @@
/// If this is set to -1, it will indicate that there is no next node to
/// the engine (i.e. this is the last node in the sort order). When it is
/// null, it means that no semantics update has been built yet.
+ int get nextNodeId => _nextNodeId;
int _nextNodeId;
void _updateNextNodeId(int value) {
if (value == _nextNodeId)
@@ -1096,7 +1097,6 @@
_nextNodeId = value;
_markDirty();
}
- int get nextNodeId => _nextNodeId;
/// The ID of the previous node in the traversal order before this node.
///
@@ -1108,6 +1108,7 @@
/// If this is set to -1, it will indicate that there is no previous node to
/// the engine (i.e. this is the first node in the sort order). When it is
/// null, it means that no semantics update has been built yet.
+ int get previousNodeId => _previousNodeId;
int _previousNodeId;
void _updatePreviousNodeId(int value) {
if (value == _previousNodeId)
@@ -1115,7 +1116,6 @@
_previousNodeId = value;
_markDirty();
}
- int get previousNodeId => _previousNodeId;
/// The currently selected text (or the position of the cursor) within [value]
/// if this node represents a text field.
@@ -2681,26 +2681,30 @@
/// [SemanticsSortOrder] manages.
/// * [OrdinalSortKey] for a sort key that sorts using an ordinal.
class SemanticsSortOrder extends Diagnosticable implements Comparable<SemanticsSortOrder> {
+ /// Creates an object that describes the sort order for a [Semantics] widget.
+ ///
/// Only one of `key` or `keys` may be specified, but at least one must
/// be specified. Specifying `key` is a shorthand for specifying
- /// `keys = <SemanticsSortKey>[key]`.
+ /// `keys: <SemanticsSortKey>[key]`.
///
- /// If [discardParentOrder] is set to true, then the
- /// [SemanticsSortOrder.keys] will replace the list of keys from the parents
- /// when merged, instead of extending them.
+ /// If [discardParentOrder] is set to true, then the [SemanticsSortOrder.keys]
+ /// will _replace_ the list of keys from the parents when merged, instead of
+ /// extending them.
SemanticsSortOrder({
SemanticsSortKey key,
List<SemanticsSortKey> keys,
this.discardParentOrder = false,
- })
- : assert(key != null || keys != null, 'One of key or keys must be specified.'),
- assert(key == null || keys == null, 'Only one of key or keys may be specified.'),
- keys = key == null ? keys : <SemanticsSortKey>[key];
+ }) : assert(key != null || keys != null, 'One of key or keys must be specified.'),
+ assert(key == null || keys == null, 'Only one of key or keys may be specified.'),
+ keys = key == null ? keys : <SemanticsSortKey>[key];
/// Whether or not this order is to replace the keys above it in the
/// semantics tree, or to be appended to them.
final bool discardParentOrder;
+ /// The keys that should be used to sort this node.
+ ///
+ /// Typically only one key is provided, using the constructor's `key` argument.
final List<SemanticsSortKey> keys;
/// Merges two sort orders by concatenating their sort key lists. If
@@ -2763,6 +2767,8 @@
/// * [SemanticsSortOrder] which manages a list of sort keys.
/// * [OrdinalSortKey] for a sort key that sorts using an ordinal.
abstract class SemanticsSortKey extends Diagnosticable implements Comparable<SemanticsSortKey> {
+ /// Abstract const constructor. This constructor enables subclasses to provide
+ /// const constructors so that they can be used in const expressions.
const SemanticsSortKey({this.name});
/// An optional name that will make this sort key only order itself
@@ -2774,14 +2780,21 @@
@override
int compareTo(SemanticsSortKey other) {
- if (other.runtimeType != runtimeType || other.name != name) {
+ if (other.runtimeType != runtimeType || other.name != name)
return 0;
- }
return doCompare(other);
}
+ /// The implementation of [compareTo].
+ ///
+ /// The argument is guaranteed to be the same type as this object.
+ ///
+ /// The method should return a negative number of this object is earlier in
+ /// the sort order than the argument; and a positive number if it comes later
+ /// in the sort order. Returning zero causes the system to default to
+ /// comparing the geometry of the nodes.
@protected
- int doCompare(SemanticsSortKey other);
+ int doCompare(covariant SemanticsSortKey other);
@override
void debugFillProperties(DiagnosticPropertiesBuilder description) {
@@ -2790,30 +2803,40 @@
}
}
-/// A [SemanticsSortKey] that sorts simply based on the ordinal given it.
+/// A [SemanticsSortKey] that sorts simply based on the `double` value it is
+/// given.
///
/// The [OrdinalSortKey] compares itself with other [OrdinalSortKey]s
/// to sort based on the order it is given.
///
+/// The ordinal value `order` is typically an integer, though it can be
+/// fractional, e.g. in order to fit between two other consecutive integers. The
+/// value must be finite (it cannot be a NaN value or infinity).
+///
/// See also:
///
/// * [SemanticsSortOrder] which manages a list of sort keys.
class OrdinalSortKey extends SemanticsSortKey {
- const OrdinalSortKey(this.order, {String name}) : super(name: name);
+ /// Creates a semantics sort key that uses a double as its key value.
+ ///
+ /// The [order] must be a finite number.
+ const OrdinalSortKey(
+ this.order, {
+ String name,
+ }) : assert(order != null),
+ assert(order > double.NEGATIVE_INFINITY),
+ assert(order < double.INFINITY),
+ super(name: name);
- /// [order] is a double which describes the order in which this node
- /// is traversed by the platform's accessibility services. Lower values
- /// will be traversed first.
+ /// A double which describes the order in which this node is traversed by the
+ /// platform's accessibility services. Lower values will be traversed first.
final double order;
@override
- int doCompare(SemanticsSortKey other) {
- assert(other.runtimeType == runtimeType);
- final OrdinalSortKey otherOrder = other;
- if (otherOrder.order == null || order == null || otherOrder.order == order) {
+ int doCompare(OrdinalSortKey other) {
+ if (other.order == null || order == null || other.order == order)
return 0;
- }
- return order.compareTo(otherOrder.order);
+ return order.compareTo(other.order);
}
@override
diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart
index a1a81b6..6aa1544 100644
--- a/packages/flutter/lib/src/widgets/framework.dart
+++ b/packages/flutter/lib/src/widgets/framework.dart
@@ -1869,10 +1869,11 @@
/// (directly or indirectly) from build methods, layout and paint callbacks, or
/// from [State.didChangeDependencies].
///
- /// This method should not be called from [State.deactivate] or [State.dispose]
- /// because the element tree is no longer stable at that time. To refer to
- /// an ancestor from one of those methods, save a reference to the ancestor
- /// in [State.didChangeDependencies].
+ /// This method should not be called from [State.dispose] because the element
+ /// tree is no longer stable at that time. To refer to an ancestor from that
+ /// method, save a reference to the ancestor in [State.didChangeDependencies].
+ /// It is safe to use this method from [State.deactivate], which is called
+ /// whenever the widget is removed from the tree.
///
/// It is also possible to call this from interaction event handlers (e.g.
/// gesture callbacks) or timers, to obtain a value once, if that value is not
@@ -1896,10 +1897,12 @@
/// This method does not establish a relationship with the target in the way
/// that [inheritFromWidgetOfExactType] does.
///
- /// This method should not be called from [State.deactivate] or [State.dispose]
- /// because the element tree is no longer stable at that time. To refer to
- /// an ancestor from one of those methods, save a reference to the ancestor
- /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+ /// This method should not be called from [State.dispose] because the element
+ /// tree is no longer stable at that time. To refer to an ancestor from that
+ /// method, save a reference to the ancestor by calling
+ /// [inheritFromWidgetOfExactType] in [State.didChangeDependencies]. It is
+ /// safe to use this method from [State.deactivate], which is called whenever
+ /// the widget is removed from the tree.
InheritedElement ancestorInheritedElementForWidgetOfExactType(Type targetType);
/// Returns the nearest ancestor widget of the given type, which must be the
@@ -1918,7 +1921,7 @@
/// This method should not be called from [State.deactivate] or [State.dispose]
/// because the widget tree is no longer stable at that time. To refer to
/// an ancestor from one of those methods, save a reference to the ancestor
- /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+ /// by calling [ancestorWidgetOfExactType] in [State.didChangeDependencies].
Widget ancestorWidgetOfExactType(Type targetType);
/// Returns the [State] object of the nearest ancestor [StatefulWidget] widget
@@ -1944,12 +1947,14 @@
/// This method should not be called from [State.deactivate] or [State.dispose]
/// because the widget tree is no longer stable at that time. To refer to
/// an ancestor from one of those methods, save a reference to the ancestor
- /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+ /// by calling [ancestorStateOfType] in [State.didChangeDependencies].
///
- /// Example:
+ /// ## Sample code
///
/// ```dart
- /// context.ancestorStateOfType(const TypeMatcher<ScrollableState>());
+ /// ScrollableState scrollable = context.ancestorStateOfType(
+ /// const TypeMatcher<ScrollableState>(),
+ /// );
/// ```
State ancestorStateOfType(TypeMatcher matcher);
@@ -1975,14 +1980,14 @@
/// it is used by [Material] so that [InkWell] widgets can trigger the ink
/// splash on the [Material]'s actual render object.
///
- /// This method should not be called from [State.deactivate] or [State.dispose]
- /// because the widget tree is no longer stable at that time. To refer to
- /// an ancestor from one of those methods, save a reference to the ancestor
- /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
- ///
/// Calling this method is relatively expensive (O(N) in the depth of the
/// tree). Only call this method if the distance from this widget to the
/// desired ancestor is known to be small and bounded.
+ ///
+ /// This method should not be called from [State.deactivate] or [State.dispose]
+ /// because the widget tree is no longer stable at that time. To refer to
+ /// an ancestor from one of those methods, save a reference to the ancestor
+ /// by calling [ancestorRenderObjectOfType] in [State.didChangeDependencies].
RenderObject ancestorRenderObjectOfType(TypeMatcher matcher);
/// Walks the ancestor chain, starting with the parent of this build context's
@@ -1998,7 +2003,7 @@
/// This method should not be called from [State.deactivate] or [State.dispose]
/// because the element tree is no longer stable at that time. To refer to
/// an ancestor from one of those methods, save a reference to the ancestor
- /// by calling [inheritFromWidgetOfExactType] in [State.didChangeDependencies].
+ /// by calling [visitAncestorElements] in [State.didChangeDependencies].
void visitAncestorElements(bool visitor(Element element));
/// Walks the children of this widget.
diff --git a/packages/flutter/test/widgets/custom_painter_test.dart b/packages/flutter/test/widgets/custom_painter_test.dart
index dd657d1..b3da2ae 100644
--- a/packages/flutter/test/widgets/custom_painter_test.dart
+++ b/packages/flutter/test/widgets/custom_painter_test.dart
@@ -347,8 +347,6 @@
),
));
- debugDumpSemanticsTree(DebugSemanticsDumpOrder.inverseHitTest);
-
final Set<SemanticsAction> allActions = SemanticsAction.values.values.toSet()
..remove(SemanticsAction.showOnScreen); // showOnScreen is non user-exposed.
@@ -656,8 +654,9 @@
firstChild.visitChildren((SemanticsNode node) {
if (node.key != null && idAssignments[node.key] != null) {
expect(idAssignments[node.key], node.id, reason:
- 'Node with key ${node.key} was previously assigned id ${idAssignments[node.key]}. '
- 'After diffing the child list, its id changed to ${node.id}. Ids must be stable.');
+ 'Node with key ${node.key} was previously assigned ID ${idAssignments[node.key]}. '
+ 'After diffing the child list, its ID changed to ${node.id}. IDs must be stable.'
+ );
}
return true;
});
