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 | /// |
7 | /// @docImport 'editable_text.dart'; |
8 | /// @docImport 'text.dart'; |
9 | library; |
10 | |
11 | import 'basic.dart'; |
12 | import 'framework.dart'; |
13 | import 'inherited_theme.dart'; |
14 | |
15 | // Examples can assume: |
16 | // late BuildContext context; |
17 | |
18 | /// The selection style to apply to descendant [EditableText] widgets which |
19 | /// don't have an explicit style. |
20 | /// |
21 | /// {@macro flutter.cupertino.CupertinoApp.defaultSelectionStyle} |
22 | /// |
23 | /// {@macro flutter.material.MaterialApp.defaultSelectionStyle} |
24 | /// |
25 | /// See also: |
26 | /// * [TextSelectionTheme]: which also creates a [DefaultSelectionStyle] for |
27 | /// the subtree. |
28 | class DefaultSelectionStyle extends InheritedTheme { |
29 | /// Creates a default selection style widget that specifies the selection |
30 | /// properties for all widgets below it in the widget tree. |
31 | const DefaultSelectionStyle({ |
32 | super.key, |
33 | this.cursorColor, |
34 | this.selectionColor, |
35 | this.mouseCursor, |
36 | required super.child, |
37 | }); |
38 | |
39 | /// A const-constructable default selection style that provides fallback |
40 | /// values (null). |
41 | /// |
42 | /// Returned from [of] when the given [BuildContext] doesn't have an enclosing |
43 | /// default selection style. |
44 | /// |
45 | /// This constructor creates a [DefaultTextStyle] with an invalid [child], |
46 | /// which means the constructed value cannot be incorporated into the tree. |
47 | const DefaultSelectionStyle.fallback({super.key}) |
48 | : cursorColor = null, |
49 | selectionColor = null, |
50 | mouseCursor = null, |
51 | super(child: const _NullWidget()); |
52 | |
53 | /// Creates a default selection style that overrides the selection styles in |
54 | /// scope at this point in the widget tree. |
55 | /// |
56 | /// Any Arguments that are not null replace the corresponding properties on the |
57 | /// default selection style for the [BuildContext] where the widget is inserted. |
58 | static Widget merge({ |
59 | Key? key, |
60 | Color? cursorColor, |
61 | Color? selectionColor, |
62 | MouseCursor? mouseCursor, |
63 | required Widget child, |
64 | }) { |
65 | return Builder( |
66 | builder: (BuildContext context) { |
67 | final DefaultSelectionStyle parent = DefaultSelectionStyle.of(context); |
68 | return DefaultSelectionStyle( |
69 | key: key, |
70 | cursorColor: cursorColor ?? parent.cursorColor, |
71 | selectionColor: selectionColor ?? parent.selectionColor, |
72 | mouseCursor: mouseCursor ?? parent.mouseCursor, |
73 | child: child, |
74 | ); |
75 | }, |
76 | ); |
77 | } |
78 | |
79 | /// The default cursor and selection color (semi-transparent grey). |
80 | /// |
81 | /// This is the color that the [Text] widget uses when the specified selection |
82 | /// color is null. |
83 | static const Color defaultColor = Color(0x80808080); |
84 | |
85 | /// The color of the text field's cursor. |
86 | /// |
87 | /// The cursor indicates the current location of the text insertion point in |
88 | /// the field. |
89 | final Color? cursorColor; |
90 | |
91 | /// The background color of selected text. |
92 | final Color? selectionColor; |
93 | |
94 | /// The [MouseCursor] for mouse pointers hovering over selectable Text widgets. |
95 | /// |
96 | /// If this property is null, [SystemMouseCursors.text] will be used. |
97 | final MouseCursor? mouseCursor; |
98 | |
99 | /// The closest instance of this class that encloses the given context. |
100 | /// |
101 | /// If no such instance exists, returns an instance created by |
102 | /// [DefaultSelectionStyle.fallback], which contains fallback values. |
103 | /// |
104 | /// Typical usage is as follows: |
105 | /// |
106 | /// ```dart |
107 | /// DefaultSelectionStyle style = DefaultSelectionStyle.of(context); |
108 | /// ``` |
109 | static DefaultSelectionStyle of(BuildContext context) { |
110 | return context.dependOnInheritedWidgetOfExactType<DefaultSelectionStyle>() ?? |
111 | const DefaultSelectionStyle.fallback(); |
112 | } |
113 | |
114 | @override |
115 | Widget wrap(BuildContext context, Widget child) { |
116 | return DefaultSelectionStyle( |
117 | cursorColor: cursorColor, |
118 | selectionColor: selectionColor, |
119 | mouseCursor: mouseCursor, |
120 | child: child, |
121 | ); |
122 | } |
123 | |
124 | @override |
125 | bool updateShouldNotify(DefaultSelectionStyle oldWidget) { |
126 | return cursorColor != oldWidget.cursorColor || |
127 | selectionColor != oldWidget.selectionColor || |
128 | mouseCursor != oldWidget.mouseCursor; |
129 | } |
130 | } |
131 | |
132 | class _NullWidget extends StatelessWidget { |
133 | const _NullWidget(); |
134 | |
135 | @override |
136 | Widget build(BuildContext context) { |
137 | throw FlutterError( |
138 | 'A DefaultSelectionStyle constructed with DefaultSelectionStyle.fallback cannot be incorporated into the widget tree, ' |
139 | 'it is meant only to provide a fallback value returned by DefaultSelectionStyle.of() ' |
140 | 'when no enclosing default selection style is present in a BuildContext.' , |
141 | ); |
142 | } |
143 | } |
144 | |