1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5import 'basic.dart';
6import 'framework.dart';
7
8class _GridPaperPainter extends CustomPainter {
9 const _GridPaperPainter({
10 required this.color,
11 required this.interval,
12 required this.divisions,
13 required this.subdivisions,
14 });
15
16 final Color color;
17 final double interval;
18 final int divisions;
19 final int subdivisions;
20
21 @override
22 void paint(Canvas canvas, Size size) {
23 final Paint linePaint = Paint()..color = color;
24 final double allDivisions = (divisions * subdivisions).toDouble();
25 for (double x = 0.0; x <= size.width; x += interval / allDivisions) {
26 linePaint.strokeWidth = (x % interval == 0.0)
27 ? 1.0
28 : (x % (interval / subdivisions) == 0.0)
29 ? 0.5
30 : 0.25;
31 canvas.drawLine(Offset(x, 0.0), Offset(x, size.height), linePaint);
32 }
33 for (double y = 0.0; y <= size.height; y += interval / allDivisions) {
34 linePaint.strokeWidth = (y % interval == 0.0)
35 ? 1.0
36 : (y % (interval / subdivisions) == 0.0)
37 ? 0.5
38 : 0.25;
39 canvas.drawLine(Offset(0.0, y), Offset(size.width, y), linePaint);
40 }
41 }
42
43 @override
44 bool shouldRepaint(_GridPaperPainter oldPainter) {
45 return oldPainter.color != color ||
46 oldPainter.interval != interval ||
47 oldPainter.divisions != divisions ||
48 oldPainter.subdivisions != subdivisions;
49 }
50
51 @override
52 bool hitTest(Offset position) => false;
53}
54
55/// A widget that draws a rectilinear grid of lines one pixel wide.
56///
57/// Useful with a [Stack] for visualizing your layout along a grid.
58///
59/// The grid's origin (where the first primary horizontal line and the first
60/// primary vertical line intersect) is at the top left of the widget.
61///
62/// The grid is drawn over the [child] widget.
63class GridPaper extends StatelessWidget {
64 /// Creates a widget that draws a rectilinear grid of 1-pixel-wide lines.
65 const GridPaper({
66 super.key,
67 this.color = const Color(0x7FC3E8F3),
68 this.interval = 100.0,
69 this.divisions = 2,
70 this.subdivisions = 5,
71 this.child,
72 }) : assert(
73 divisions > 0,
74 'The "divisions" property must be greater than zero. If there were no divisions, the grid paper would not paint anything.',
75 ),
76 assert(
77 subdivisions > 0,
78 'The "subdivisions" property must be greater than zero. If there were no subdivisions, the grid paper would not paint anything.',
79 );
80
81 /// The color to draw the lines in the grid.
82 ///
83 /// Defaults to a light blue commonly seen on traditional grid paper.
84 final Color color;
85
86 /// The distance between the primary lines in the grid, in logical pixels.
87 ///
88 /// Each primary line is one logical pixel wide.
89 final double interval;
90
91 /// The number of major divisions within each primary grid cell.
92 ///
93 /// This is the number of major divisions per [interval], including the
94 /// primary grid's line.
95 ///
96 /// The lines after the first are half a logical pixel wide.
97 ///
98 /// If this is set to 2 (the default), then for each [interval] there will be
99 /// a 1-pixel line on the left, a half-pixel line in the middle, and a 1-pixel
100 /// line on the right (the latter being the 1-pixel line on the left of the
101 /// next [interval]).
102 final int divisions;
103
104 /// The number of minor divisions within each major division, including the
105 /// major division itself.
106 ///
107 /// If [subdivisions] is 5 (the default), it means that there will be four
108 /// lines between each major ([divisions]) line.
109 ///
110 /// The subdivision lines after the first are a quarter of a logical pixel wide.
111 final int subdivisions;
112
113 /// The widget below this widget in the tree.
114 ///
115 /// {@macro flutter.widgets.ProxyWidget.child}
116 final Widget? child;
117
118 @override
119 Widget build(BuildContext context) {
120 return CustomPaint(
121 foregroundPainter: _GridPaperPainter(
122 color: color,
123 interval: interval,
124 divisions: divisions,
125 subdivisions: subdivisions,
126 ),
127 child: child,
128 );
129 }
130}
131