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