platform.dart 3.72 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6
import '_platform_io.dart'
  if (dart.library.html) '_platform_web.dart' as _platform;
7

8 9 10
/// The [TargetPlatform] that matches the platform on which the framework is
/// currently executing.
///
11 12
/// This is the default value of [ThemeData.platform] (hence the name). Widgets
/// from the material library should use [Theme.of] to determine the current
13
/// platform for styling purposes, rather than using [defaultTargetPlatform].
14 15
/// Widgets and render objects at lower layers that try to emulate the
/// underlying platform can depend on [defaultTargetPlatform] directly. The
Dan Field's avatar
Dan Field committed
16
/// [dart:io.Platform] object should only be used directly when it's critical to
17 18
/// actually know the current platform, without any overrides possible (for
/// example, when a system API is about to be called).
19
///
20 21 22 23
/// In a test environment, the platform returned is [TargetPlatform.android]
/// regardless of the host platform. (Android was chosen because the tests were
/// originally written assuming Android-like behavior, and we added platform
/// 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 28
///
/// Tests can also create specific platform tests by and adding a `variant:`
/// argument to the test and using a [TargetPlatformVariant].
29
//
30
// When adding support for a new platform (e.g. Windows Phone, Raspberry Pi),
31
// first create a new value on the [TargetPlatform] enum, then add a rule for
32 33 34 35 36 37 38
// selecting that platform here.
//
// It would be incorrect to make a platform that isn't supported by
// [TargetPlatform] default to the behavior of another platform, because doing
// that would mean we'd be stuck with that platform forever emulating the other,
// and we'd never be able to introduce dedicated behavior for that platform
// (since doing so would be a big breaking change).
39 40 41 42 43 44 45 46 47
TargetPlatform get defaultTargetPlatform => _platform.defaultTargetPlatform;

/// The platform that user interaction should adapt to target.
///
/// The [defaultTargetPlatform] getter returns the current platform.
enum TargetPlatform {
  /// Android: <https://www.android.com/>
  android,

48
  /// Fuchsia: <https://fuchsia.dev/fuchsia-src/concepts>
49 50
  fuchsia,

51
  /// iOS: <https://www.apple.com/ios/>
52
  iOS,
53

54 55 56 57
  /// Linux: <https://www.linux.org>
  linux,

  /// macOS: <https://www.apple.com/macos>
58
  macOS,
59 60 61

  /// Windows: <https://www.windows.com>
  windows,
62
}
63

64 65 66 67 68
/// Override the [defaultTargetPlatform].
///
/// Setting this to null returns the [defaultTargetPlatform] to its original
/// value (based on the actual current platform).
///
69 70 71 72 73
/// Generally speaking this override is only useful for tests. To change the
/// platform that widgets resemble, consider using the platform override APIs
/// (such as [ThemeData.platform] in the material library) instead.
///
/// Setting [debugDefaultTargetPlatformOverride] (as opposed to, say,
74
/// [ThemeData.platform]) will cause unexpected and undesirable effects. For
75 76 77 78 79 80 81 82
/// example, setting this to [TargetPlatform.iOS] when the application is
/// running on Android will cause the TalkBack accessibility tool on Android to
/// be confused because it would be receiving data intended for iOS VoiceOver.
/// Similarly, setting it to [TargetPlatform.android] while on iOS will cause
/// certainly widgets to work assuming the presence of a system-wide back
/// button, which will make those widgets unusable since iOS has no such button.
///
/// In general, therefore, this property should not be used in release builds.
83
TargetPlatform? debugDefaultTargetPlatformOverride;