firka/flutter
3
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More docs updates for services. (#7633)

Browse Source
This commit is contained in:
Ian Hickson
2017-01-24 23:34:16 -08:00
committed by GitHub
parent 6bd578ff52
commit 94fab77bea
9 changed files with 135 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/flutter/lib/src/services/binding.dart
View File

@@ -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

31
packages/flutter/lib/src/services/clipboard.dart
View File

@@ -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<Null> 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<ClipboardData> getData(String format) async {
Map<String, dynamic> result = await PlatformMessages.invokeMethod(
_kChannelName, 'Clipboard.getData', <String>[format]);
_kChannelName,
'Clipboard.getData',
<String>[format]
);
if (result == null)
return null;
return new ClipboardData(text: result['text']);

17
packages/flutter/lib/src/services/haptic_feedback.dart
View File

@@ -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<Null> vibrate() async {
await PlatformMessages.invokeMethod('flutter/platform', 'HapticFeedback.vibrate');
}

17
packages/flutter/lib/src/services/path_provider.dart
View File

@@ -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<Directory> getTemporaryDirectory() async {
Map<String, dynamic> 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<Directory> getApplicationDocumentsDirectory() async {
Map<String, dynamic> result = await PlatformMessages.invokeMethod(
_kChannelName, 'PathProvider.getApplicationDocumentsDirectory');

107
packages/flutter/lib/src/services/platform_messages.dart
View File

@@ -30,15 +30,17 @@ dynamic _decodeJSON(String message) {
typedef Future<ByteData> _PlatformMessageHandler(ByteData message);
/// Sends message to and receives messages from the underlying platform.
/// Sends message to and receives messages from platform plugins.
///
/// See: <https://flutter.io/platform-services/>
class PlatformMessages {
PlatformMessages._();
/// Handlers for incoming platform messages.
// Handlers for incoming messages from platform plugins.
static final Map<String, _PlatformMessageHandler> _handlers =
<String, _PlatformMessageHandler>{};
/// Mock handlers that intercept and respond to outgoing messages.
// Mock handlers that intercept and respond to outgoing messages.
static final Map<String, _PlatformMessageHandler> _mockHandlers =
<String, _PlatformMessageHandler>{};
@@ -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<ByteData> 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<String> 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<dynamic> 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<dynamic> invokeMethod(String channel, String method, [ List<dynamic> args = const <Null>[] ]) {
return sendJSON(channel, <String, dynamic>{
'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<ByteData> 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<String> 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<dynamic> 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<ByteData> 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<String> 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<dynamic> handler(dynamic message)) {
if (handler == null) {
setMockStringMessageHandler(channel, null);

9
packages/flutter/lib/src/services/raw_keyboard.dart
View File

@@ -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 <http://www.usb.org/developers/hidpage/Hut1_12v2.pdf>
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.

8
packages/flutter/lib/src/services/system_navigator.dart
View File

@@ -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<Null> pop() async {
await PlatformMessages.invokeMethod('flutter/platform', 'SystemNavigator.pop');
}

8
packages/flutter/lib/src/services/system_sound.dart
View File

@@ -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<Null> play(SystemSoundType type) async {
await PlatformMessages.invokeMethod(
'flutter/platform',

5
packages/flutter/lib/src/services/url_launcher.dart
View File

@@ -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<Null> launch(String urlString) async {
await PlatformMessages.invokeMethod(
'flutter/platform',