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
5/// @docImport 'package:flutter/material.dart';
6/// @docImport 'package:flutter/rendering.dart';
7///
8/// @docImport 'text_span.dart';
9/// @docImport 'text_style.dart';
10library;
11
12import 'dart:ui' show TextDirection;
13
14export 'dart:ui' show
15 BlendMode,
16 BlurStyle,
17 Canvas,
18 Clip,
19 Color,
20 ColorFilter,
21 FilterQuality,
22 FontFeature,
23 FontStyle,
24 FontVariation,
25 FontWeight,
26 GlyphInfo,
27 ImageShader,
28 Locale,
29 MaskFilter,
30 Offset,
31 Paint,
32 PaintingStyle,
33 Path,
34 PathFillType,
35 PathOperation,
36 RRect,
37 RSTransform,
38 Radius,
39 Rect,
40 Shader,
41 Shadow,
42 Size,
43 StrokeCap,
44 StrokeJoin,
45 TextAffinity,
46 TextAlign,
47 TextBaseline,
48 TextBox,
49 TextDecoration,
50 TextDecorationStyle,
51 TextDirection,
52 TextHeightBehavior,
53 TextLeadingDistribution,
54 TextPosition,
55 TileMode,
56 VertexMode;
57
58export 'package:flutter/foundation.dart' show VoidCallback;
59
60// Intentionally not exported:
61// - Image, instantiateImageCodec, decodeImageFromList:
62// We use ui.* to make it very explicit that these are low-level image APIs.
63// Generally, higher layers provide more reasonable APIs around images.
64// - lerpDouble:
65// Hopefully this will eventually become Double.lerp.
66// - Paragraph, ParagraphBuilder, ParagraphStyle, TextBox:
67// These are low-level text primitives. Use this package's TextPainter API.
68// - Picture, PictureRecorder, Scene, SceneBuilder:
69// These are low-level primitives. Generally, the rendering layer makes these moot.
70// - Gradient:
71// Use this package's higher-level Gradient API instead.
72// - window, WindowPadding
73// These are generally wrapped by other APIs so we always refer to them directly
74// as ui.* to avoid making them seem like high-level APIs.
75
76/// The description of the difference between two objects, in the context of how
77/// it will affect the rendering.
78///
79/// Used by [TextSpan.compareTo] and [TextStyle.compareTo].
80///
81/// The values in this enum are ordered such that they are in increasing order
82/// of cost. A value with index N implies all the values with index less than N.
83/// For example, [layout] (index 3) implies [paint] (2).
84enum RenderComparison {
85 /// The two objects are identical (meaning deeply equal, not necessarily
86 /// [dart:core.identical]).
87 identical,
88
89 /// The two objects are identical for the purpose of layout, but may be different
90 /// in other ways.
91 ///
92 /// For example, maybe some event handlers changed.
93 metadata,
94
95 /// The two objects are different but only in ways that affect paint, not layout.
96 ///
97 /// For example, only the color is changed.
98 ///
99 /// [RenderObject.markNeedsPaint] would be necessary to handle this kind of
100 /// change in a render object.
101 paint,
102
103 /// The two objects are different in ways that affect layout (and therefore paint).
104 ///
105 /// For example, the size is changed.
106 ///
107 /// This is the most drastic level of change possible.
108 ///
109 /// [RenderObject.markNeedsLayout] would be necessary to handle this kind of
110 /// change in a render object.
111 layout,
112}
113
114/// The two cardinal directions in two dimensions.
115///
116/// The axis is always relative to the current coordinate space. This means, for
117/// example, that a [horizontal] axis might actually be diagonally from top
118/// right to bottom left, due to some local [Transform] applied to the scene.
119///
120/// See also:
121///
122/// * [AxisDirection], which is a directional version of this enum (with values
123/// like left and right, rather than just horizontal).
124/// * [TextDirection], which disambiguates between left-to-right horizontal
125/// content and right-to-left horizontal content.
126enum Axis {
127 /// Left and right.
128 ///
129 /// See also:
130 ///
131 /// * [TextDirection], which disambiguates between left-to-right horizontal
132 /// content and right-to-left horizontal content.
133 horizontal,
134
135 /// Up and down.
136 vertical,
137}
138
139/// Returns the opposite of the given [Axis].
140///
141/// Specifically, returns [Axis.horizontal] for [Axis.vertical], and
142/// vice versa.
143///
144/// See also:
145///
146/// * [flipAxisDirection], which does the same thing for [AxisDirection] values.
147Axis flipAxis(Axis direction) {
148 return switch (direction) {
149 Axis.horizontal => Axis.vertical,
150 Axis.vertical => Axis.horizontal,
151 };
152}
153
154/// A direction in which boxes flow vertically.
155///
156/// This is used by the flex algorithm (e.g. [Column]) to decide in which
157/// direction to draw boxes.
158///
159/// This is also used to disambiguate `start` and `end` values (e.g.
160/// [MainAxisAlignment.start] or [CrossAxisAlignment.end]).
161///
162/// See also:
163///
164/// * [TextDirection], which controls the same thing but horizontally.
165enum VerticalDirection {
166 /// Boxes should start at the bottom and be stacked vertically towards the top.
167 ///
168 /// The "start" is at the bottom, the "end" is at the top.
169 up,
170
171 /// Boxes should start at the top and be stacked vertically towards the bottom.
172 ///
173 /// The "start" is at the top, the "end" is at the bottom.
174 down,
175}
176
177/// A direction along either the horizontal or vertical [Axis] in which the
178/// origin, or zero position, is determined.
179///
180/// This value relates to the direction in which the scroll offset increases
181/// from the origin. This value does not represent the direction of user input
182/// that may be modifying the scroll offset, such as from a drag. For the
183/// active scrolling direction, see [ScrollDirection].
184///
185/// {@tool dartpad}
186/// This sample shows a [CustomScrollView], with [Radio] buttons in the
187/// [AppBar.bottom] that change the [AxisDirection] to illustrate different
188/// configurations.
189///
190/// ** See code in examples/api/lib/painting/axis_direction/axis_direction.0.dart **
191/// {@end-tool}
192///
193/// See also:
194///
195/// * [ScrollDirection], the direction of active scrolling, relative to the positive
196/// scroll offset axis given by an [AxisDirection] and a [GrowthDirection].
197/// * [GrowthDirection], the direction in which slivers and their content are
198/// ordered, relative to the scroll offset axis as specified by
199/// [AxisDirection].
200/// * [CustomScrollView.anchor], the relative position of the zero scroll
201/// offset in a viewport and inflection point for [AxisDirection]s of the
202/// same cardinal [Axis].
203/// * [axisDirectionIsReversed], which returns whether traveling along the
204/// given axis direction visits coordinates along that axis in numerically
205/// decreasing order.
206enum AxisDirection {
207 /// A direction in the [Axis.vertical] where zero is at the bottom and
208 /// positive values are above it: `⇈`
209 ///
210 /// Alphabetical content with a [GrowthDirection.forward] would have the A at
211 /// the bottom and the Z at the top.
212 ///
213 /// For example, the behavior of a [ListView] with [ListView.reverse] set to
214 /// true would have this axis direction.
215 ///
216 /// See also:
217 ///
218 /// * [axisDirectionIsReversed], which returns whether traveling along the
219 /// given axis direction visits coordinates along that axis in numerically
220 /// decreasing order.
221 up,
222
223 /// A direction in the [Axis.horizontal] where zero is on the left and
224 /// positive values are to the right of it: `⇉`
225 ///
226 /// Alphabetical content with a [GrowthDirection.forward] would have the A on
227 /// the left and the Z on the right. This is the ordinary reading order for a
228 /// horizontal set of tabs in an English application, for example.
229 ///
230 /// For example, the behavior of a [ListView] with [ListView.scrollDirection]
231 /// set to [Axis.horizontal] would have this axis direction.
232 ///
233 /// See also:
234 ///
235 /// * [axisDirectionIsReversed], which returns whether traveling along the
236 /// given axis direction visits coordinates along that axis in numerically
237 /// decreasing order.
238 right,
239
240 /// A direction in the [Axis.vertical] where zero is at the top and positive
241 /// values are below it: `⇊`
242 ///
243 /// Alphabetical content with a [GrowthDirection.forward] would have the A at
244 /// the top and the Z at the bottom. This is the ordinary reading order for a
245 /// vertical list.
246 ///
247 /// For example, the default behavior of a [ListView] would have this axis
248 /// direction.
249 ///
250 /// See also:
251 ///
252 /// * [axisDirectionIsReversed], which returns whether traveling along the
253 /// given axis direction visits coordinates along that axis in numerically
254 /// decreasing order.
255 down,
256
257 /// A direction in the [Axis.horizontal] where zero is to the right and
258 /// positive values are to the left of it: `⇇`
259 ///
260 /// Alphabetical content with a [GrowthDirection.forward] would have the A at
261 /// the right and the Z at the left. This is the ordinary reading order for a
262 /// horizontal set of tabs in a Hebrew application, for example.
263 ///
264 /// For example, the behavior of a [ListView] with [ListView.scrollDirection]
265 /// set to [Axis.horizontal] and [ListView.reverse] set to true would have
266 /// this axis direction.
267 ///
268 /// See also:
269 ///
270 /// * [axisDirectionIsReversed], which returns whether traveling along the
271 /// given axis direction visits coordinates along that axis in numerically
272 /// decreasing order.
273 left,
274}
275
276/// Returns the [Axis] that contains the given [AxisDirection].
277///
278/// Specifically, returns [Axis.vertical] for [AxisDirection.up] and
279/// [AxisDirection.down] and returns [Axis.horizontal] for [AxisDirection.left]
280/// and [AxisDirection.right].
281Axis axisDirectionToAxis(AxisDirection axisDirection) {
282 return switch (axisDirection) {
283 AxisDirection.up || AxisDirection.down => Axis.vertical,
284 AxisDirection.left || AxisDirection.right => Axis.horizontal,
285 };
286}
287
288/// Returns the [AxisDirection] in which reading occurs in the given [TextDirection].
289///
290/// Specifically, returns [AxisDirection.left] for [TextDirection.rtl] and
291/// [AxisDirection.right] for [TextDirection.ltr].
292AxisDirection textDirectionToAxisDirection(TextDirection textDirection) {
293 return switch (textDirection) {
294 TextDirection.rtl => AxisDirection.left,
295 TextDirection.ltr => AxisDirection.right,
296 };
297}
298
299/// Returns the opposite of the given [AxisDirection].
300///
301/// Specifically, returns [AxisDirection.up] for [AxisDirection.down] (and
302/// vice versa), as well as [AxisDirection.left] for [AxisDirection.right] (and
303/// vice versa).
304///
305/// See also:
306///
307/// * [flipAxis], which does the same thing for [Axis] values.
308AxisDirection flipAxisDirection(AxisDirection axisDirection) {
309 return switch (axisDirection) {
310 AxisDirection.up => AxisDirection.down,
311 AxisDirection.right => AxisDirection.left,
312 AxisDirection.down => AxisDirection.up,
313 AxisDirection.left => AxisDirection.right,
314 };
315}
316
317/// Returns whether traveling along the given axis direction visits coordinates
318/// along that axis in numerically decreasing order.
319///
320/// Specifically, returns true for [AxisDirection.up] and [AxisDirection.left]
321/// and false for [AxisDirection.down] and [AxisDirection.right].
322bool axisDirectionIsReversed(AxisDirection axisDirection) {
323 return switch (axisDirection) {
324 AxisDirection.up || AxisDirection.left => true,
325 AxisDirection.down || AxisDirection.right => false,
326 };
327}
328