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_test/flutter_test.dart';
6library;
7
8import 'package:flutter/foundation.dart';
9
10/// An enum identifying standard UI components.
11///
12/// This enum is used to attach a key to a widget identifying it as a standard
13/// UI component for testing and discovery purposes.
14///
15/// It is used by the testing infrastructure (e.g. the `find` object in the
16/// Flutter test framework) to positively identify and/or activate specific
17/// widgets as representing standard UI components, since many of these
18/// components vary slightly in the icons or tooltips that they use, and making
19/// an effective test matcher for them is fragile and error prone.
20///
21/// The keys don't have any effect on the functioning of the UI elements, they
22/// are just a means of identifying them. A widget won't be treated specially if
23/// it has this key, other than to be found by the testing infrastructure. If
24/// tests are not searching for them, then adding them to a widget serves no
25/// purpose.
26///
27/// Any widget with the [key] from a value here applied to it will be considered
28/// to be that type of standard UI component in tests.
29///
30/// Types included here are generally only those for which it can be difficult
31/// or fragile to create a reliable test matcher for. It is not (nor should it
32/// become) an exhaustive list of standard UI components.
33///
34/// See also:
35///
36/// - [CommonFinders.backButton], which in tests is used as `find.backButton()`.
37/// - [CommonFinders.closeButton], which in tests is used as `find.closeButton()`.
38enum StandardComponentType {
39 /// Indicates the associated widget is a standard back button, typically used
40 /// to navigate back to the previous screen.
41 backButton,
42
43 /// Indicates the associated widget is a close button, typically used to
44 /// dismiss a dialog or modal sheet.
45 closeButton,
46
47 /// Indicates the associated widget is a "more" button, typically used to
48 /// display a menu of additional options.
49 moreButton,
50
51 /// Indicates the associated widget is a drawer button, typically used to open
52 /// a drawer.
53 drawerButton;
54
55 /// Returns a [ValueKey] for this [StandardComponentType].
56 ///
57 /// Attach this key to a widget to indicate it is a standard UI component.
58 ValueKey<StandardComponentType> get key => ValueKey<StandardComponentType>(this);
59}
60