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 '_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).
45TargetPlatform 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.
59enum 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.
98TargetPlatform? debugDefaultTargetPlatformOverride;
99