firka/flutter
firka/flutter
4
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #880 from abarth/basic_widget_docs

Browse Source 
Add more dartdoc for basic widgets
This commit is contained in:
Adam Barth 2015-12-10 15:31:51 -08:00
commit 9353102a7d
5 changed files with 119 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
packages/flutter/lib/src/rendering/custom_layout.dart
View File

@ -23,7 +23,7 @@ abstract class MultiChildLayoutDelegate {
Map<Object, RenderBox> _idToChild;
Set<RenderBox> _debugChildrenNeedingLayout;
/// Returns the size of this object given the incomming constraints.
/// Returns the size of this object given the incoming constraints.
/// The size cannot reflect the instrinsic sizes of the children.
/// If this layout has a fixed width or height the returned size
/// can reflect that.

30
packages/flutter/lib/src/rendering/proxy_box.dart
View File

@ -164,13 +164,15 @@ class RenderConstrainedBox extends RenderProxyBox {
}
}
/// A render object that, for both width and height, imposes a tight constraint
/// on its child that is a multiple (typically less than 1.0) of the maximum
/// constraint it received from its parent on that axis. If the factor for a
/// given axis is null, then the constraints from the parent are just passed
/// through instead.
/// Sizes itself to a fraction of the total available space.
///
/// It then tries to size itself the size of its child.
/// For both its width and width height, this render object imposes a tight
/// constraint on its child that is a multiple (typically less than 1.0) of the
/// maximum constraint it received from its parent on that axis. If the factor
/// for a given axis is null, then the constraints from the parent are just
/// passed through instead.
///
/// It then tries to size itself t the size of its child.
class RenderFractionallySizedBox extends RenderProxyBox {
RenderFractionallySizedBox({
RenderBox child,
@ -181,9 +183,11 @@ class RenderFractionallySizedBox extends RenderProxyBox {
assert(_heightFactor == null || _heightFactor >= 0.0);
}
/// The multiple to apply to the incoming maximum width constraint to use as
/// the tight width constraint for the child, or null to pass through the
/// constraints given by the parent.
/// If non-null, the factor of the incoming width to use.
///
/// If non-null, the child is given a tight width constraint that is the max
/// incoming width constraint multipled by this factor. If null, the child is
/// given the incoming width constraings.
double get widthFactor => _widthFactor;
double _widthFactor;
void set widthFactor (double value) {
@ -194,9 +198,11 @@ class RenderFractionallySizedBox extends RenderProxyBox {
markNeedsLayout();
}
/// The multiple to apply to the incoming maximum height constraint to use as
/// the tight height constraint for the child, or null to pass through the
/// constraints given by the parent.
/// If non-null, the factor of the incoming height to use.
///
/// If non-null, the child is given a tight height constraint that is the max
/// incoming width constraint multipled by this factor. If null, the child is
/// given the incoming width constraings.
double get heightFactor => _heightFactor;
double _heightFactor;
void set heightFactor (double value) {

12
packages/flutter/lib/src/rendering/shifted_box.dart
View File

@ -249,10 +249,10 @@ class RenderPositionedBox extends RenderShiftedBox {
/// A delegate for computing the layout of a render object with a single child.
class OneChildLayoutDelegate {
/// Returns the size of this object given the incomming constraints.
/// Returns the size of this object given the incoming constraints.
Size getSize(BoxConstraints constraints) => constraints.biggest;
/// Returns the box constraints for the child given the incomming constraints.
/// Returns the box constraints for the child given the incoming constraints.
BoxConstraints getConstraintsForChild(BoxConstraints constraints) => constraints;
/// Returns the position where the child should be placed given the size of this object and the size of the child.
@ -325,6 +325,7 @@ class RenderCustomOneChildLayoutBox extends RenderShiftedBox {
}
}
/// Positions its child vertically according to the child's baseline.
class RenderBaseline extends RenderShiftedBox {
RenderBaseline({
@ -338,8 +339,10 @@ class RenderBaseline extends RenderShiftedBox {
assert(baselineType != null);
}
double _baseline;
/// The number of logical pixels from the top of this box at which to position
/// the child's baseline.
double get baseline => _baseline;
double _baseline;
void set baseline (double value) {
assert(value != null);
if (_baseline == value)
@ -348,8 +351,9 @@ class RenderBaseline extends RenderShiftedBox {
markNeedsLayout();
}
TextBaseline _baselineType;
/// The type of baseline to use for positioning the child.
TextBaseline get baselineType => _baselineType;
TextBaseline _baselineType;
void set baselineType (TextBaseline value) {
assert(value != null);
if (_baselineType == value)

100
packages/flutter/lib/src/widgets/basic.dart
View File

@ -126,7 +126,9 @@ class ShaderMask extends OneChildRenderObjectWidget {
}
}
/// Paints a [BoxDecoration] either before or after its child paints.
/// Paints a [Decoration] either before or after its child paints.
///
/// Commonly used with [BoxDecoration].
class DecoratedBox extends OneChildRenderObjectWidget {
DecoratedBox({
Key key,
@ -139,6 +141,8 @@ class DecoratedBox extends OneChildRenderObjectWidget {
}
/// What decoration to paint.
///
/// Commonly a [BoxDecoration].
final Decoration decoration;
/// Where to paint the box decoration.
@ -541,11 +545,23 @@ class ConstrainedBox extends OneChildRenderObjectWidget {
}
}
/// Sizes itself to a fraction of the total available space.
///
/// See [RenderFractionallySizedBox] for details.
class FractionallySizedBox extends OneChildRenderObjectWidget {
FractionallySizedBox({ Key key, this.width, this.height, Widget child })
: super(key: key, child: child);
/// If non-null, the factor of the incoming width to use.
///
/// If non-null, the child is given a tight width constraint that is the max
/// incoming width constraint multipled by this factor.
final double width;
/// If non-null, the factor of the incoming height to use.
///
/// If non-null, the child is given a tight height constraint that is the max
/// incoming height constraint multipled by this factor.
final double height;
RenderFractionallySizedBox createRenderObject() => new RenderFractionallySizedBox(
@ -567,13 +583,28 @@ class FractionallySizedBox extends OneChildRenderObjectWidget {
}
}
/// A render object that imposes different constraints on its child than it gets
/// from its parent, possibly allowing the child to overflow the parent.
///
/// See [RenderOverflowBox] for details.
class OverflowBox extends OneChildRenderObjectWidget {
OverflowBox({ Key key, this.minWidth, this.maxWidth, this.minHeight, this.maxHeight, Widget child })
: super(key: key, child: child);
/// The minimum width constraint to give the child. Set this to null (the
/// default) to use the constraint from the parent instead.
final double minWidth;
/// The maximum width constraint to give the child. Set this to null (the
/// default) to use the constraint from the parent instead.
final double maxWidth;
/// The minimum height constraint to give the child. Set this to null (the
/// default) to use the constraint from the parent instead.
final double minHeight;
/// The maximum height constraint to give the child. Set this to null (the
/// default) to use the constraint from the parent instead.
final double maxHeight;
RenderOverflowBox createRenderObject() => new RenderOverflowBox(
@ -614,12 +645,19 @@ class OffStage extends OneChildRenderObjectWidget {
RenderOffStage createRenderObject() => new RenderOffStage();
}
/// Forces child to layout at a specific aspect ratio.
///
/// See [RenderAspectRatio] for details.
class AspectRatio extends OneChildRenderObjectWidget {
AspectRatio({ Key key, this.aspectRatio, Widget child })
: super(key: key, child: child) {
assert(aspectRatio != null);
}
/// The aspect ratio to use when computing the height from the width.
///
/// The aspect ratio is expressed as a ratio of width to height. For example,
/// a 16:9 width:height aspect ratio would have a value of 16.0/9.0.
final double aspectRatio;
RenderAspectRatio createRenderObject() => new RenderAspectRatio(aspectRatio: aspectRatio);
@ -676,6 +714,7 @@ class IntrinsicHeight extends OneChildRenderObjectWidget {
RenderIntrinsicHeight createRenderObject() => new RenderIntrinsicHeight();
}
/// Positions its child vertically according to the child's baseline.
class Baseline extends OneChildRenderObjectWidget {
Baseline({ Key key, this.baseline, this.baselineType: TextBaseline.alphabetic, Widget child })
: super(key: key, child: child) {
@ -683,7 +722,11 @@ class Baseline extends OneChildRenderObjectWidget {
assert(baselineType != null);
}
final double baseline; // in pixels
/// The number of logical pixels from the top of this box at which to position
/// the child's baseline.
final double baseline;
/// The type of baseline to use for positioning the child.
final TextBaseline baselineType;
RenderBaseline createRenderObject() => new RenderBaseline(baseline: baseline, baselineType: baselineType);
@ -760,10 +803,10 @@ class SizeObserver extends OneChildRenderObjectWidget {
}
// CONVENIENCE CLASS TO COMBINE COMMON PAINTING, POSITIONING, AND SIZING NODES
// CONTAINER
/// A convenience widget that combines common painting, positioning, and sizing widgets.
class Container extends StatelessComponent {
Container({
Key key,
this.child,
@ -879,12 +922,17 @@ class Container extends StatelessComponent {
if (height != null)
description.add('height: $height');
}
}
// LAYOUT NODES
/// Uses the block layout algorithm for its children.
///
/// This widget is rarely used directly. Instead, consider using [Block], which
/// combines the block layout algorithm with scrolling behavior.
///
/// For details about the block layout algorithm, see [RenderBlockBase].
class BlockBody extends MultiChildRenderObjectWidget {
BlockBody(List<Widget> children, {
Key key,
@ -893,6 +941,7 @@ class BlockBody extends MultiChildRenderObjectWidget {
assert(direction != null);
}
/// The direction to use as the main axis.
final BlockDirection direction;
RenderBlock createRenderObject() => new RenderBlock(direction: direction);
@ -1183,8 +1232,12 @@ class Flexible extends ParentDataWidget {
}
}
class Paragraph extends LeafRenderObjectWidget {
Paragraph({ Key key, this.text }) : super(key: key) {
/// A raw paragraph of text.
///
/// This class is rarely used directly. Instead, consider using [Text], which
/// integrates with [DefaultTextStyle].
class RawText extends LeafRenderObjectWidget {
RawText({ Key key, this.text }) : super(key: key) {
assert(text != null);
}
@ -1192,19 +1245,26 @@ class Paragraph extends LeafRenderObjectWidget {
RenderParagraph createRenderObject() => new RenderParagraph(text);
void updateRenderObject(RenderParagraph renderObject, Paragraph oldWidget) {
void updateRenderObject(RenderParagraph renderObject, RawText oldWidget) {
renderObject.text = text;
}
}
/// A convience widget for paragraphs of text with heterogeneous style.
///
/// The elements paramter is a recusrive list of lists that matches the
/// following grammar:
///
/// `elements ::= "string" | [<text-style> <elements>*]``
///
/// Where "string" is text to display and text-style is an instance of
/// TextStyle. The text-style applies to all of the elements that follow.
class StyledText extends StatelessComponent {
// elements ::= "string" | [<text-style> <elements>*]
// Where "string" is text to display and text-style is an instance of
// TextStyle. The text-style applies to all of the elements that follow.
StyledText({ this.elements, Key key }) : super(key: key) {
assert(_toSpan(elements) != null);
}
/// The recursive list of lists that describes the text and style to paint.
final dynamic elements;
TextSpan _toSpan(dynamic element) {
@ -1220,10 +1280,11 @@ class StyledText extends StatelessComponent {
}
Widget build(BuildContext context) {
return new Paragraph(text: _toSpan(elements));
return new RawText(text: _toSpan(elements));
}
}
/// The text style to apply to descendant [Text] widgets without explicit style.
class DefaultTextStyle extends InheritedWidget {
DefaultTextStyle({
Key key,
@ -1234,8 +1295,10 @@ class DefaultTextStyle extends InheritedWidget {
assert(child != null);
}
/// The text style to apply.
final TextStyle style;
/// The closest instance of this class that encloses the given context.
static TextStyle of(BuildContext context) {
DefaultTextStyle result = context.inheritFromWidgetOfType(DefaultTextStyle);
return result?.style;
@ -1249,12 +1312,23 @@ class DefaultTextStyle extends InheritedWidget {
}
}
/// A run of text.
///
/// By default, the text will be styled using the closest enclosing
/// [DefaultTextStyle].
class Text extends StatelessComponent {
Text(this.data, { Key key, this.style }) : super(key: key) {
assert(data != null);
}
/// The text to display.
final String data;
/// If non-null, the style to use for this text.
///
/// If the style's "inherit" property is true, the style will be merged with
/// the closest enclosing [DefaultTextStyle]. Otherwise, the style will
/// replace the closest enclosing [DefaultTextStyle].
final TextStyle style;
Widget build(BuildContext context) {
@ -1267,7 +1341,7 @@ class Text extends StatelessComponent {
}
if (combinedStyle != null)
text = new StyledTextSpan(combinedStyle, <TextSpan>[text]);
return new Paragraph(text: text);
return new RawText(text: text);
}
void debugFillDescription(List<String> description) {

6
packages/flutter/lib/src/widgets/pageable_list.dart
View File

@ -14,7 +14,11 @@ import 'framework.dart';
import 'homogeneous_viewport.dart';
import 'scrollable.dart';
enum ItemsSnapAlignment { item, adjacentItem }
/// Controls what alignment items use when settling.
enum ItemsSnapAlignment {
item,
adjacentItem
}
typedef void PageChangedCallback(int newPage);