Unverified Commit 10393a12 authored by Ian Hickson's avatar Ian Hickson Committed by GitHub

Add some more documentation. (#14717)

parent f6fe41f1
......@@ -29,6 +29,14 @@ const double _kForegroundScreenOpacityFraction = 0.7;
/// 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 @@ class CupertinoPicker extends StatefulWidget {
/// 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 @@ class _CupertinoPickerState extends State<CupertinoPicker> {
@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;
}
}
......@@ -37,12 +37,13 @@ enum _ScaffoldSlot {
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,
......
......@@ -1076,8 +1076,8 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
/// 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 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
/// 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 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
_nextNodeId = value;
_markDirty();
}
int get nextNodeId => _nextNodeId;
/// The ID of the previous node in the traversal order before this node.
///
......@@ -1108,6 +1108,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
/// 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 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
_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 @@ String _concatStrings({
/// [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 @@ class SemanticsSortOrder extends Diagnosticable implements Comparable<SemanticsS
/// * [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 @@ abstract class SemanticsSortKey extends Diagnosticable implements Comparable<Sem
@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 @@ abstract class SemanticsSortKey extends Diagnosticable implements Comparable<Sem
}
}
/// 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
......
......@@ -1869,10 +1869,11 @@ abstract class BuildContext {
/// (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 @@ abstract class BuildContext {
/// 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 @@ abstract class BuildContext {
/// 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 @@ abstract class BuildContext {
/// 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 @@ abstract class BuildContext {
/// 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 @@ abstract class BuildContext {
/// 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.
......
......@@ -347,8 +347,6 @@ void _defineTests() {
),
));
debugDumpSemanticsTree(DebugSemanticsDumpOrder.inverseHitTest);
final Set<SemanticsAction> allActions = SemanticsAction.values.values.toSet()
..remove(SemanticsAction.showOnScreen); // showOnScreen is non user-exposed.
......@@ -656,8 +654,9 @@ class _DiffTester {
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;
});
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment