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 | import '_platform_io.dart' |
6 | if (dart.library.js_util) '_platform_web.dart' as platform; |
7 | |
8 | /// The [TargetPlatform] that matches the platform on which the framework is |
9 | /// currently executing. |
10 | /// |
11 | /// This is the default value of [ThemeData.platform] (hence the name). Widgets |
12 | /// from the material library should use [Theme.of] to determine the current |
13 | /// platform for styling purposes, rather than using [defaultTargetPlatform]. |
14 | /// Widgets and render objects at lower layers that try to emulate the |
15 | /// underlying platform can depend on [defaultTargetPlatform] directly. The |
16 | /// [dart:io.Platform] object should only be used directly when it's critical to |
17 | /// actually know the current platform, without any overrides possible (for |
18 | /// example, when a system API is about to be called). |
19 | /// |
20 | /// In a test environment, the platform returned is [TargetPlatform.android] |
21 | /// regardless of the host platform. (Android was chosen because the tests were |
22 | /// originally written assuming Android-like behavior, and we added platform |
23 | /// adaptations for iOS later). Tests can check iOS behavior by using the |
24 | /// platform override APIs (such as [ThemeData.platform] in the material |
25 | /// library) or by setting [debugDefaultTargetPlatformOverride]. |
26 | /// |
27 | /// Tests can also create specific platform tests by and adding a `variant:` |
28 | /// argument to the test and using a [TargetPlatformVariant]. |
29 | /// |
30 | /// See also: |
31 | /// |
32 | /// * [kIsWeb], a boolean which is true if the application is running on the |
33 | /// web, where [defaultTargetPlatform] returns which platform the browser is |
34 | /// running on. |
35 | // |
36 | // When adding support for a new platform (e.g. Windows Phone, Raspberry Pi), |
37 | // first create a new value on the [TargetPlatform] enum, then add a rule for |
38 | // selecting that platform in `_platform_io.dart` and `_platform_web.dart`. |
39 | // |
40 | // It would be incorrect to make a platform that isn't supported by |
41 | // [TargetPlatform] default to the behavior of another platform, because doing |
42 | // that would mean we'd be stuck with that platform forever emulating the other, |
43 | // and we'd never be able to introduce dedicated behavior for that platform |
44 | // (since doing so would be a big breaking change). |
45 | TargetPlatform get defaultTargetPlatform => platform.defaultTargetPlatform; |
46 | |
47 | /// The platform that user interaction should adapt to target. |
48 | /// |
49 | /// The [defaultTargetPlatform] getter returns the current platform. |
50 | /// |
51 | /// When using the "flutter run" command, the "o" key will toggle between |
52 | /// values of this enum when updating [debugDefaultTargetPlatformOverride]. |
53 | /// This lets one test how the application will work on various platforms |
54 | /// without having to switch emulators or physical devices. |
55 | // |
56 | // When you add values here, make sure to also add them to |
57 | // nextPlatform() in flutter_tools/lib/src/resident_runner.dart so that |
58 | // the tool can support the new platform for its "o" option. |
59 | enum TargetPlatform { |
60 | /// Android: <https://www.android.com/> |
61 | android, |
62 | |
63 | /// Fuchsia: <https://fuchsia.dev/fuchsia-src/concepts> |
64 | fuchsia, |
65 | |
66 | /// iOS: <https://www.apple.com/ios/> |
67 | iOS, |
68 | |
69 | /// Linux: <https://www.linux.org> |
70 | linux, |
71 | |
72 | /// macOS: <https://www.apple.com/macos> |
73 | macOS, |
74 | |
75 | /// Windows: <https://www.windows.com> |
76 | windows, |
77 | } |
78 | |
79 | /// Override the [defaultTargetPlatform]. |
80 | /// |
81 | /// Setting this to null returns the [defaultTargetPlatform] to its original |
82 | /// value (based on the actual current platform). |
83 | /// |
84 | /// Generally speaking this override is only useful for tests. To change the |
85 | /// platform that widgets resemble, consider using the platform override APIs |
86 | /// (such as [ThemeData.platform] in the material library) instead. |
87 | /// |
88 | /// Setting [debugDefaultTargetPlatformOverride] (as opposed to, say, |
89 | /// [ThemeData.platform]) will cause unexpected and undesirable effects. For |
90 | /// example, setting this to [TargetPlatform.iOS] when the application is |
91 | /// running on Android will cause the TalkBack accessibility tool on Android to |
92 | /// be confused because it would be receiving data intended for iOS VoiceOver. |
93 | /// Similarly, setting it to [TargetPlatform.android] while on iOS will cause |
94 | /// certainly widgets to work assuming the presence of a system-wide back |
95 | /// button, which will make those widgets unusable since iOS has no such button. |
96 | /// |
97 | /// In general, therefore, this property should not be used in release builds. |
98 | TargetPlatform? debugDefaultTargetPlatformOverride; |
99 | |