From e548d4656218fa18fc8eb6c174f59ec9246db679 Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Sat, 27 May 2017 16:59:01 -0700 Subject: [PATCH] Document GridPaper (#10357) --- packages/flutter/lib/src/material/app.dart | 8 +-- .../flutter/lib/src/widgets/grid_paper.dart | 57 ++++++++++++++----- 2 files changed, 46 insertions(+), 19 deletions(-) diff --git a/packages/flutter/lib/src/material/app.dart b/packages/flutter/lib/src/material/app.dart index 0c03be5b6e..17b34c1697 100644 --- a/packages/flutter/lib/src/material/app.dart +++ b/packages/flutter/lib/src/material/app.dart @@ -246,7 +246,7 @@ class _MaterialAppState extends State { checkerboardRasterCacheImages: widget.checkerboardRasterCacheImages, checkerboardOffscreenLayers: widget.checkerboardOffscreenLayers, showSemanticsDebugger: widget.showSemanticsDebugger, - debugShowCheckedModeBanner: widget.debugShowCheckedModeBanner + debugShowCheckedModeBanner: widget.debugShowCheckedModeBanner, ) ); @@ -256,8 +256,8 @@ class _MaterialAppState extends State { color: const Color(0xE0F9BBE0), interval: 8.0, divisions: 2, - subDivisions: 1, - child: result + subdivisions: 1, + child: result, ); } return true; @@ -265,7 +265,7 @@ class _MaterialAppState extends State { return new ScrollConfiguration( behavior: new _MaterialScrollBehavior(), - child: result + child: result, ); } } diff --git a/packages/flutter/lib/src/widgets/grid_paper.dart b/packages/flutter/lib/src/widgets/grid_paper.dart index 1d8fd0da40..374cc819f7 100644 --- a/packages/flutter/lib/src/widgets/grid_paper.dart +++ b/packages/flutter/lib/src/widgets/grid_paper.dart @@ -12,25 +12,25 @@ class _GridPaperPainter extends CustomPainter { this.color, this.interval, this.divisions, - this.subDivisions + this.subdivisions }); final Color color; final double interval; final int divisions; - final int subDivisions; + final int subdivisions; @override void paint(Canvas canvas, Size size) { final Paint linePaint = new Paint() ..color = color; - final double allDivisions = (divisions * subDivisions).toDouble(); + final double allDivisions = (divisions * subdivisions).toDouble(); for (double x = 0.0; x <= size.width; x += interval / allDivisions) { - linePaint.strokeWidth = (x % interval == 0.0) ? 1.0 : (x % (interval / subDivisions) == 0.0) ? 0.5: 0.25; + linePaint.strokeWidth = (x % interval == 0.0) ? 1.0 : (x % (interval / subdivisions) == 0.0) ? 0.5 : 0.25; canvas.drawLine(new Offset(x, 0.0), new Offset(x, size.height), linePaint); } for (double y = 0.0; y <= size.height; y += interval / allDivisions) { - linePaint.strokeWidth = (y % interval == 0.0) ? 1.0 : (y % (interval / subDivisions) == 0.0) ? 0.5: 0.25; + linePaint.strokeWidth = (y % interval == 0.0) ? 1.0 : (y % (interval / subdivisions) == 0.0) ? 0.5 : 0.25; canvas.drawLine(new Offset(0.0, y), new Offset(size.width, y), linePaint); } } @@ -40,38 +40,65 @@ class _GridPaperPainter extends CustomPainter { return oldPainter.color != color || oldPainter.interval != interval || oldPainter.divisions != divisions - || oldPainter.subDivisions != subDivisions; + || oldPainter.subdivisions != subdivisions; } @override bool hitTest(Offset position) => false; } -/// A widget that draws a rectilinear grid of 1px wide lines. +/// A widget that draws a rectilinear grid of lines one pixel wide. /// /// Useful with a [Stack] for visualizing your layout along a grid. +/// +/// The grid's origin (where the first primary horizontal line and the first +/// primary vertical line intersect) is at the top left of the widget. +/// +/// The grid is drawn over the [child] widget. class GridPaper extends StatelessWidget { - /// Creates a widget that draws a rectilinear grid of 1px wide lines. + /// Creates a widget that draws a rectilinear grid of 1-pixel-wide lines. const GridPaper({ Key key, this.color: const Color(0x7FC3E8F3), this.interval: 100.0, this.divisions: 2, - this.subDivisions: 5, - this.child - }) : super(key: key); + this.subdivisions: 5, + this.child, + }) : assert(divisions > 0, 'The "divisions" property must be greater than zero. If there were no divisions, the grid paper would not paint anything.'), + assert(subdivisions > 0, 'The "subdivisions" property must be greater than zero. If there were no subdivisions, the grid paper would not paint anything.'), + super(key: key); /// The color to draw the lines in the grid. + /// + /// Defaults to a light blue commonly seen on traditional gridpaper. final Color color; /// The distance between the primary lines in the grid, in logical pixels. + /// + /// Each primary line is one logical pixel wide. final double interval; /// The number of major divisions within each primary grid cell. + /// + /// This is the number of major divisions per [interval], including the + /// primary grid's line. + /// + /// The lines after the first are half a logical pixel wide. + /// + /// If this is set to 2 (the default), then for each [interval] there will be + /// a 1-pixel line on the left, a half-pixel line in the middle, and a 1-pixel + /// line on the right (the latter being the 1-pixel line on the left of the + /// next [interval]). final int divisions; - /// The number of minor divisions within each major division. - final int subDivisions; + /// The number of minor divisions within each major division, including the + /// major division itself. + /// + /// If [subdivisions] is 5 (the default), it means that there will be four + /// lines between each major ([divisions]) line. + /// + /// The subdivision lines after the first are a quarter of a logical pixel wide. + final int subdivisions; /// The widget below this widget in the tree. final Widget child; @@ -83,9 +110,9 @@ class GridPaper extends StatelessWidget { color: color, interval: interval, divisions: divisions, - subDivisions: subDivisions + subdivisions: subdivisions, ), - child: child + child: child, ); } }