diff --git a/packages/flutter/lib/src/services/binding.dart b/packages/flutter/lib/src/services/binding.dart index 4dfdaaaf1b..cfa79ecf24 100644 --- a/packages/flutter/lib/src/services/binding.dart +++ b/packages/flutter/lib/src/services/binding.dart @@ -14,7 +14,7 @@ import 'platform_messages.dart'; /// Listens for platform messages and directs them to [PlatformMessages]. /// /// The ServicesBinding also registers a [LicenseEntryCollector] that exposes -/// the licenses found in the LICENSE file stored at the root of the asset +/// the licenses found in the `LICENSE` file stored at the root of the asset /// bundle. abstract class ServicesBinding extends BindingBase { @override diff --git a/packages/flutter/lib/src/services/clipboard.dart b/packages/flutter/lib/src/services/clipboard.dart index 759192441e..1ef9a427cc 100644 --- a/packages/flutter/lib/src/services/clipboard.dart +++ b/packages/flutter/lib/src/services/clipboard.dart @@ -6,27 +6,31 @@ import 'dart:async'; import 'platform_messages.dart'; -/// Data stored on the system clip board. +/// Data stored on the system clipboard. /// -/// The system clip board can contain data of various media types. This data -/// structure currently supports only plain text data in the [text] property. +/// The system clipboard can contain data of various media types. This data +/// structure currently supports only plain text data, in the [text] property. class ClipboardData { /// Creates data for the system clipboard. const ClipboardData({ this.text }); - /// Plain text data on the clip board. + /// Plain text variant of this clipboard data. final String text; } const String _kChannelName = 'flutter/platform'; -/// An interface to the system's clipboard. +/// Utility methods for interacting with the system's clipboard. class Clipboard { - /// Constants for common [getData] [format] types. - static final String kTextPlain = 'text/plain'; - Clipboard._(); + // Constants for common [getData] [format] types. + + /// Plain text data format string. + /// + /// Used with [getData]. + static const String kTextPlain = 'text/plain'; + /// Stores the given clipboard data on the clipboard. static Future setData(ClipboardData data) async { await PlatformMessages.invokeMethod( @@ -40,10 +44,17 @@ class Clipboard { /// Retrieves data from the clipboard that matches the given format. /// - /// * `format` is a media type, such as `text/plain`. + /// The `format` argument specifies the media type, such as `text/plain`, of + /// the data to obtain. + /// + /// Returns a future which completes to null if the data could not be + /// obtained, and to a [ClipboardData] object if it could. static Future getData(String format) async { Map result = await PlatformMessages.invokeMethod( - _kChannelName, 'Clipboard.getData', [format]); + _kChannelName, + 'Clipboard.getData', + [format] + ); if (result == null) return null; return new ClipboardData(text: result['text']); diff --git a/packages/flutter/lib/src/services/haptic_feedback.dart b/packages/flutter/lib/src/services/haptic_feedback.dart index 771655dd96..1a1a968b43 100644 --- a/packages/flutter/lib/src/services/haptic_feedback.dart +++ b/packages/flutter/lib/src/services/haptic_feedback.dart @@ -6,21 +6,20 @@ import 'dart:async'; import 'platform_messages.dart'; -/// Allows access to the haptic feedback interface on the device. This API is -/// intentionally terse since it calls default platform behavior. It is not -/// suitable for use if you require more flexible access to device sensors and -/// peripherals. +/// Allows access to the haptic feedback interface on the device. +/// +/// This API is intentionally terse since it calls default platform behavior. It +/// is not suitable for precise control of the system's haptic feedback module. class HapticFeedback { HapticFeedback._(); /// Provides haptic feedback to the user for a short duration. /// - /// Platform Specific Notes: + /// On iOS, this uses the platform "sound" for vibration (via + /// `AudioServicesPlaySystemSound`). /// - /// * _iOS_: Uses the platform "sound" for vibration (via - /// AudioServicesPlaySystemSound) - /// * _Android_: Uses the platform haptic feedback API that simulates a short - /// a short tap on a virtual keyboard. + /// On Android, this uses the platform haptic feedback API to simulates a + /// short tap on a virtual keyboard. static Future vibrate() async { await PlatformMessages.invokeMethod('flutter/platform', 'HapticFeedback.vibrate'); } diff --git a/packages/flutter/lib/src/services/path_provider.dart b/packages/flutter/lib/src/services/path_provider.dart index 79761dd964..e2519d019f 100644 --- a/packages/flutter/lib/src/services/path_provider.dart +++ b/packages/flutter/lib/src/services/path_provider.dart @@ -13,16 +13,16 @@ const String _kChannelName = 'flutter/platform'; class PathProvider { PathProvider._(); - /// Path to the temporary directory on the device. Files in this directory - /// may be cleared at any time. This does *not* return a new temporary - /// directory. Instead, the caller is responsible for creating + /// Path to the temporary directory on the device. + /// + /// Files in this directory may be cleared at any time. This does *not* return + /// a new temporary directory. Instead, the caller is responsible for creating /// (and cleaning up) files or directories within this directory. This /// directory is scoped to the calling application. /// - /// Examples: + /// On iOS, this uses the `NSTemporaryDirectory` API. /// - /// * _iOS_: `NSTemporaryDirectory()` - /// * _Android_: `getCacheDir()` on the context. + /// On Android, this uses the `getCacheDir` API on the context. static Future getTemporaryDirectory() async { Map result = await PlatformMessages.invokeMethod( _kChannelName, 'PathProvider.getTemporaryDirectory'); @@ -35,10 +35,9 @@ class PathProvider { /// to the application and will only be cleared when the application itself /// is deleted. /// - /// Examples: + /// On iOS, this uses the `NSDocumentsDirectory` API. /// - /// * _iOS_: `NSDocumentsDirectory` - /// * _Android_: The AppData directory. + /// On Android, this returns the AppData directory. static Future getApplicationDocumentsDirectory() async { Map result = await PlatformMessages.invokeMethod( _kChannelName, 'PathProvider.getApplicationDocumentsDirectory'); diff --git a/packages/flutter/lib/src/services/platform_messages.dart b/packages/flutter/lib/src/services/platform_messages.dart index ec8ec0d5ae..f46fd5d600 100644 --- a/packages/flutter/lib/src/services/platform_messages.dart +++ b/packages/flutter/lib/src/services/platform_messages.dart @@ -30,15 +30,17 @@ dynamic _decodeJSON(String message) { typedef Future _PlatformMessageHandler(ByteData message); -/// Sends message to and receives messages from the underlying platform. +/// Sends message to and receives messages from platform plugins. +/// +/// See: class PlatformMessages { PlatformMessages._(); - /// Handlers for incoming platform messages. + // Handlers for incoming messages from platform plugins. static final Map _handlers = {}; - /// Mock handlers that intercept and respond to outgoing messages. + // Mock handlers that intercept and respond to outgoing messages. static final Map _mockHandlers = {}; @@ -85,7 +87,10 @@ class PlatformMessages { } } - /// Send a binary message to the host application. + /// Send a binary message to the platform plugins on the given channel. + /// + /// Returns a [Future] which completes to the received response, undecoded, in + /// binary form. static Future sendBinary(String channel, ByteData message) { final _PlatformMessageHandler handler = _mockHandlers[channel]; if (handler != null) @@ -93,16 +98,37 @@ class PlatformMessages { return _sendPlatformMessage(channel, message); } - /// Send a string message to the host application. + /// Send a string message to the platform plugins on the given channel. + /// + /// The message is encoded as UTF-8. + /// + /// Returns a [Future] which completes to the received response, decoded as a + /// UTF-8 string, or to an error, if the decoding fails. static Future sendString(String channel, String message) async { return _decodeUTF8(await sendBinary(channel, _encodeUTF8(message))); } - /// Sends a JSON-encoded message to the host application and JSON-decodes the response. + /// Send a JSON-encoded message to the platform plugins on the given channel. + /// + /// The message is encoded as JSON, then the JSON is encoded as UTF-8. + /// + /// Returns a [Future] which completes to the received response, decoded as a + /// UTF-8-encoded JSON representation of a JSON value (a [String], [bool], + /// [double], [List], or [Map]), or to an error, if the decoding fails. static Future sendJSON(String channel, dynamic json) async { return _decodeJSON(await sendString(channel, _encodeJSON(json))); } + /// Send a method call to the platform plugins on the given channel. + /// + /// Method calls are encoded as a JSON object with two keys, `method` with the + /// string given in the `method` argument, and `args` with the arguments given + /// in the `args` optional argument, as a JSON list. This JSON object is then + /// encoded as a UTF-8 string. + /// + /// The response from the method call is decoded as UTF-8, then the UTF-8 is + /// decoded as JSON. The returned [Future] completes to this fully decoded + /// response, or to an error, if the decoding fails. static Future invokeMethod(String channel, String method, [ List args = const [] ]) { return sendJSON(channel, { 'method': method, @@ -110,39 +136,56 @@ class PlatformMessages { }); } - /// Set a callback for receiving binary messages from the platform. + /// Set a callback for receiving messages from the platform plugins on the + /// given channel, without decoding them. /// - /// The given callback will replace the currently registered callback (if any). + /// The given callback will replace the currently registered callback for that + /// channel, if any. + /// + /// The handler's return value, if non-null, is sent as a response, unencoded. static void setBinaryMessageHandler(String channel, Future handler(ByteData message)) { _handlers[channel] = handler; } - /// Set a callback for receiving string messages from the platform. + /// Set a callback for receiving messages from the platform plugins on the + /// given channel, decoding the data as UTF-8. /// - /// The given callback will replace the currently registered callback (if any). + /// The given callback will replace the currently registered callback for that + /// channel, if any. + /// + /// The handler's return value, if non-null, is sent as a response, encoded as + /// a UTF-8 string. static void setStringMessageHandler(String channel, Future handler(String message)) { setBinaryMessageHandler(channel, (ByteData message) async { return _encodeUTF8(await handler(_decodeUTF8(message))); }); } - /// Set a callback for receiving JSON messages from the platform. + /// Set a callback for receiving messages from the platform plugins on the + /// given channel, decoding the data as UTF-8 JSON. /// - /// Messages received are decoded as JSON before being passed to the given - /// callback. The result of the callback is encoded as JSON before being - /// returned as the response to the message. + /// The given callback will replace the currently registered callback for that + /// channel, if any. /// - /// The given callback will replace the currently registered callback (if any). + /// The handler's return value, if non-null, is sent as a response, encoded as + /// JSON and then as a UTF-8 string. static void setJSONMessageHandler(String channel, Future handler(dynamic message)) { setStringMessageHandler(channel, (String message) async { return _encodeJSON(await handler(_decodeJSON(message))); }); } - /// Sets a message handler that intercepts outgoing messages in binary form. + /// Set a mock callback for intercepting messages from the `send*` methods on + /// this class, on the given channel, without decoding them. /// - /// The given callback will replace the currently registered callback (if any). - /// To remove the mock handler, pass `null` as the `handler` argument. + /// The given callback will replace the currently registered mock callback for + /// that channel, if any. To remove the mock handler, pass `null` as the + /// `handler` argument. + /// + /// The handler's return value, if non-null, is used as a response, unencoded. + /// + /// This is intended for testing. Messages intercepted in this manner are not + /// sent to platform plugins. static void setMockBinaryMessageHandler(String channel, Future handler(ByteData message)) { if (handler == null) _mockHandlers.remove(channel); @@ -150,10 +193,18 @@ class PlatformMessages { _mockHandlers[channel] = handler; } - /// Sets a message handler that intercepts outgoing messages in string form. + /// Set a mock callback for intercepting messages from the `send*` methods on + /// this class, on the given channel, decoding them as UTF-8. /// - /// The given callback will replace the currently registered callback (if any). - /// To remove the mock handler, pass `null` as the `handler` argument. + /// The given callback will replace the currently registered mock callback for + /// that channel, if any. To remove the mock handler, pass `null` as the + /// `handler` argument. + /// + /// The handler's return value, if non-null, is used as a response, encoded as + /// UTF-8. + /// + /// This is intended for testing. Messages intercepted in this manner are not + /// sent to platform plugins. static void setMockStringMessageHandler(String channel, Future handler(String message)) { if (handler == null) { setMockBinaryMessageHandler(channel, null); @@ -164,10 +215,18 @@ class PlatformMessages { } } - /// Sets a message handler that intercepts outgoing messages in JSON form. + /// Set a mock callback for intercepting messages from the `send*` methods on + /// this class, on the given channel, decoding them as UTF-8 JSON. /// - /// The given callback will replace the currently registered callback (if any). - /// To remove the mock handler, pass `null` as the `handler` argument. + /// The given callback will replace the currently registered mock callback for + /// that channel, if any. To remove the mock handler, pass `null` as the + /// `handler` argument. + /// + /// The handler's return value, if non-null, is used as a response, encoded as + /// UTF-8 JSON. + /// + /// This is intended for testing. Messages intercepted in this manner are not + /// sent to platform plugins. static void setMockJSONMessageHandler(String channel, Future handler(dynamic message)) { if (handler == null) { setMockStringMessageHandler(channel, null); diff --git a/packages/flutter/lib/src/services/raw_keyboard.dart b/packages/flutter/lib/src/services/raw_keyboard.dart index eb10bd0205..cbfecee99a 100644 --- a/packages/flutter/lib/src/services/raw_keyboard.dart +++ b/packages/flutter/lib/src/services/raw_keyboard.dart @@ -16,6 +16,7 @@ import 'platform_messages.dart'; /// See also: /// /// * [RawKeyEventDataAndroid] + // * [RawKeyEventDataFuchsia] /// * [RawKeyEvent] /// * [RawKeyDownEvent] /// * [RawKeyUpEvent] @@ -28,7 +29,7 @@ abstract class RawKeyEventData { /// Platform-specific key event data for Android. /// /// This object contains information about key events obtained from Android's -/// KeyEvent interface. +/// `KeyEvent` interface. class RawKeyEventDataAndroid extends RawKeyEventData { /// Creates a key event data structure specific for Android. /// @@ -61,7 +62,7 @@ class RawKeyEventDataAndroid extends RawKeyEventData { /// Platform-specific key event data for Fuchsia. /// /// This object contains information about key events obtained from Fuchsia's -/// KeyData interface. +/// `KeyData` interface. class RawKeyEventDataFuchsia extends RawKeyEventData { /// Creates a key event data structure specific for Android. /// @@ -77,9 +78,9 @@ class RawKeyEventDataFuchsia extends RawKeyEventData { /// See final int hidUsage; - /// The unicode code point represented by the key event, if any. + /// The Unicode code point represented by the key event, if any. /// - /// If there is no unicode code point, this value is zero. + /// If there is no Unicode code point, this value is zero. final int codePoint; /// The modifiers that we present when the key event occured. diff --git a/packages/flutter/lib/src/services/system_navigator.dart b/packages/flutter/lib/src/services/system_navigator.dart index d9cd3ddfe6..a4402a6840 100644 --- a/packages/flutter/lib/src/services/system_navigator.dart +++ b/packages/flutter/lib/src/services/system_navigator.dart @@ -13,10 +13,12 @@ class SystemNavigator { /// Instructs the system navigator to remove this activity from the stack and /// return to the previous activity. /// - /// Platform Specific Notes: + /// On iOS, calls to this method are ignored because Apple's human interface + /// guidelines state that applications should not exit themselves. /// - /// On iOS, this is a no-op because Apple's human interface guidelines state - /// that applications should not exit themselves. + /// This method should be preferred over calling `dart:io`'s [exit] method, as + /// the latter may cause the underlying platform to act as if the application + /// had crashed. static Future pop() async { await PlatformMessages.invokeMethod('flutter/platform', 'SystemNavigator.pop'); } diff --git a/packages/flutter/lib/src/services/system_sound.dart b/packages/flutter/lib/src/services/system_sound.dart index 47ced0bf5d..c97c11d553 100644 --- a/packages/flutter/lib/src/services/system_sound.dart +++ b/packages/flutter/lib/src/services/system_sound.dart @@ -6,19 +6,19 @@ import 'dart:async'; import 'platform_messages.dart'; -/// A sound provided by the system +/// A sound provided by the system. enum SystemSoundType { /// A short indication that a button was pressed. click, } -/// Allows easy access to the library of short system specific sounds for -/// common tasks. +/// Provides access to the library of short system specific sounds for common +/// tasks. class SystemSound { SystemSound._(); /// Play the specified system sound. If that sound is not present on the - /// system, this method is a no-op. + /// system, the call is ignored. static Future play(SystemSoundType type) async { await PlatformMessages.invokeMethod( 'flutter/platform', diff --git a/packages/flutter/lib/src/services/url_launcher.dart b/packages/flutter/lib/src/services/url_launcher.dart index 5d098ee8c0..a320984cbc 100644 --- a/packages/flutter/lib/src/services/url_launcher.dart +++ b/packages/flutter/lib/src/services/url_launcher.dart @@ -13,11 +13,6 @@ class UrlLauncher { /// Parse the specified URL string and delegate handling of the same to the /// underlying platform. - /// - /// Arguments: - /// - /// * [urlString]: The URL string to be parsed by the underlying platform and - /// before it attempts to launch the same. static Future launch(String urlString) async { await PlatformMessages.invokeMethod( 'flutter/platform',