Unverified Commit fa6f9a03 authored by Ian Hickson's avatar Ian Hickson Committed by GitHub

Various documentation improvements (#12855)

parent c17099f4
......@@ -30,8 +30,10 @@ final TextStyle _kBackgroundButtonTextStyle = _kButtonTextStyle.copyWith(
);
const EdgeInsets _kButtonPadding = const EdgeInsets.all(16.0);
const EdgeInsets _kBackgroundButtonPadding =
const EdgeInsets.symmetric(vertical: 16.0, horizontal: 64.0);
const EdgeInsets _kBackgroundButtonPadding = const EdgeInsets.symmetric(
vertical: 16.0,
horizontal: 64.0,
);
/// An iOS-style button.
///
......
......@@ -132,7 +132,7 @@ class MaterialApp extends StatefulWidget {
/// This value is passed unmodified to [WidgetsApp.title].
final String title;
/// If non-null this function is called to produce the app's
/// If non-null this callback is called to produce the app's
/// title string, otherwise [title] is used.
///
/// The [onGenerateTitle] `context` parameter includes the [WidgetsApp]'s
......@@ -141,6 +141,9 @@ class MaterialApp extends StatefulWidget {
///
/// This callback function must not return null.
///
/// The [onGenerateTitle] callback is called each time the [MaterialApp]
/// rebuilds.
///
/// This value is passed unmodified to [WidgetsApp.onGenerateTitle].
final GenerateAppTitle onGenerateTitle;
......
......@@ -9,18 +9,18 @@ import 'colors.dart';
import 'list_tile.dart';
import 'material.dart';
/// The alginment of a [Drawer] which is used to identify positioning
/// of the [Drawer]
///
/// The possible alignments of a [Drawer].
enum DrawerAlignment {
/// Denotes that the [Drawer] is at the start side of the [Scaffold]
/// i.e. left side when Directionality is LTR
/// and right side when Directionality is RTL
/// Denotes that the [Drawer] is at the start side of the [Scaffold].
///
/// This corresponds to the left side when the text direction is left-to-right
/// and the right side when the text direction is right-to-left.
start,
/// Denotes that the [Drawer] is at the end side of the [Scaffold]
/// i.e. right side when Directionality is LTR
/// and left side when Directionality is RTL
/// Denotes that the [Drawer] is at the end side of the [Scaffold].
///
/// This corresponds to the right side when the text direction is left-to-right
/// and the left side when the text direction is right-to-left.
end,
}
......@@ -122,8 +122,8 @@ class Drawer extends StatelessWidget {
///
/// See also:
///
/// * [Drawer]
/// * [Scaffold.drawer]
/// * [Drawer], a container with the default width of a drawer.
/// * [Scaffold.drawer], the [Scaffold] slot for showing a drawer.
class DrawerController extends StatefulWidget {
/// Creates a controller for a [Drawer].
///
......@@ -143,9 +143,10 @@ class DrawerController extends StatefulWidget {
/// Typically a [Drawer].
final Widget child;
/// The alginment of a [Drawer] which is used to identify positioning
/// of the [Drawer] i.e. either start-side or end-side
/// The alignment of the [Drawer].
///
/// This controls the direction in which the user should swipe to open and
/// close the drawer.
final DrawerAlignment alignment;
@override
......
......@@ -15,11 +15,11 @@ import 'system_channels.dart';
///
/// See also:
///
/// * [RawKeyEventDataAndroid]
// * [RawKeyEventDataFuchsia]
/// * [RawKeyEvent]
/// * [RawKeyDownEvent]
/// * [RawKeyUpEvent]
/// * [RawKeyEventDataAndroid], a specialization for Android.
/// * [RawKeyEventDataFuchsia], a specialization for Fuchsia.
/// * [RawKeyDownEvent] and [RawKeyUpEvent], the classes that hold the
/// reference to [RawKeyEventData] subclasses.
/// * [RawKeyboard], which uses these interfaces to expose key data.
@immutable
abstract class RawKeyEventData {
/// Abstract const constructor. This constructor enables subclasses to provide
......@@ -31,6 +31,10 @@ abstract class RawKeyEventData {
///
/// This object contains information about key events obtained from Android's
/// `KeyEvent` interface.
///
/// See also:
///
/// * [RawKeyboard], which uses this interface to expose key data.
class RawKeyEventDataAndroid extends RawKeyEventData {
/// Creates a key event data structure specific for Android.
///
......@@ -68,6 +72,10 @@ class RawKeyEventDataAndroid extends RawKeyEventData {
///
/// This object contains information about key events obtained from Fuchsia's
/// `KeyData` interface.
///
/// See also:
///
/// * [RawKeyboard], which uses this interface to expose key data.
class RawKeyEventDataFuchsia extends RawKeyEventData {
/// Creates a key event data structure specific for Android.
///
......@@ -105,8 +113,9 @@ class RawKeyEventDataFuchsia extends RawKeyEventData {
///
/// See also:
///
/// * [RawKeyDownEvent]
/// * [RawKeyUpEvent]
/// * [RawKeyDownEvent], a specialization for events representing the user pressing a key.
/// * [RawKeyUpEvent], a specialization for events representing the user releasing a key.
/// * [RawKeyboard], which uses this interface to expose key data.
/// * [RawKeyboardListener], a widget that listens for raw key events.
@immutable
abstract class RawKeyEvent {
......@@ -115,27 +124,9 @@ abstract class RawKeyEvent {
@required this.data,
});
/// Platform-specific information about the key event.
final RawKeyEventData data;
}
/// The user has pressed a key on the keyboard.
class RawKeyDownEvent extends RawKeyEvent {
/// Creates a key event that represents the user pressing a key.
const RawKeyDownEvent({
@required RawKeyEventData data,
}) : super(data: data);
}
/// The user has released a key on the keyboard.
class RawKeyUpEvent extends RawKeyEvent {
/// Creates a key event that represents the user releasing a key.
const RawKeyUpEvent({
@required RawKeyEventData data,
}) : super(data: data);
}
RawKeyEvent _toRawKeyEvent(Map<String, dynamic> message) {
/// Creates a concrete [RawKeyEvent] class from a message in the form received
/// on the [SystemChannels.keyEvent] channel.
factory RawKeyEvent.fromMessage(Map<String, dynamic> message) {
RawKeyEventData data;
final String keymap = message['keymap'];
......@@ -171,6 +162,34 @@ RawKeyEvent _toRawKeyEvent(Map<String, dynamic> message) {
default:
throw new FlutterError('Unknown key event type: $type');
}
}
/// Platform-specific information about the key event.
final RawKeyEventData data;
}
/// The user has pressed a key on the keyboard.
///
/// See also:
///
/// * [RawKeyboard], which uses this interface to expose key data.
class RawKeyDownEvent extends RawKeyEvent {
/// Creates a key event that represents the user pressing a key.
const RawKeyDownEvent({
@required RawKeyEventData data,
}) : super(data: data);
}
/// The user has released a key on the keyboard.
///
/// See also:
///
/// * [RawKeyboard], which uses this interface to expose key data.
class RawKeyUpEvent extends RawKeyEvent {
/// Creates a key event that represents the user releasing a key.
const RawKeyUpEvent({
@required RawKeyEventData data,
}) : super(data: data);
}
/// An interface for listening to raw key events.
......@@ -185,9 +204,11 @@ RawKeyEvent _toRawKeyEvent(Map<String, dynamic> message) {
///
/// See also:
///
/// * [RawKeyEvent]
/// * [RawKeyDownEvent]
/// * [RawKeyUpEvent]
/// * [RawKeyDownEvent] and [RawKeyUpEvent], the classes used to describe
/// specific raw key events.
/// * [RawKeyboardListener], a widget that listens for raw key events.
/// * [SystemChannels.keyEvent], the low-level channel used for receiving
/// events from the system.
class RawKeyboard {
RawKeyboard._() {
SystemChannels.keyEvent.setMessageHandler(_handleKeyEvent);
......@@ -215,7 +236,7 @@ class RawKeyboard {
Future<dynamic> _handleKeyEvent(dynamic message) async {
if (_listeners.isEmpty)
return;
final RawKeyEvent event = _toRawKeyEvent(message);
final RawKeyEvent event = new RawKeyEvent.fromMessage(message);
if (event == null)
return;
for (ValueChanged<RawKeyEvent> listener in new List<ValueChanged<RawKeyEvent>>.from(_listeners))
......
......@@ -106,7 +106,8 @@ class SystemChrome {
/// be displayed in.
///
/// The `orientation` argument is a list of [DeviceOrientation] enum values.
/// The empty list is synonymous with having all options enabled.
/// The empty list causes the application to defer to the operating system
/// default.
static Future<Null> setPreferredOrientations(List<DeviceOrientation> orientations) async {
await SystemChannels.platform.invokeMethod(
'SystemChrome.setPreferredOrientations',
......
......@@ -117,6 +117,9 @@ class WidgetsApp extends StatefulWidget {
/// localized title.
///
/// This callback function must not return null.
///
/// The [onGenerateTitle] callback is called each time the [WidgetsApp]
/// rebuilds.
final GenerateAppTitle onGenerateTitle;
/// The default text style for [Text] in the application.
......
......@@ -84,6 +84,9 @@ abstract class WidgetsBindingObserver {
/// box, and false otherwise. The [WidgetsApp] widget uses this
/// mechanism to notify the [Navigator] widget that it should pop
/// its current route if possible.
///
/// This method exposes the `popRoute` notification from
/// [SystemChannels.navigation].
Future<bool> didPopRoute() => new Future<bool>.value(false);
/// Called when the host tells the app to push a new route onto the
......@@ -92,11 +95,16 @@ abstract class WidgetsBindingObserver {
/// Observers are expected to return true if they were able to
/// handle the notification. Observers are notified in registration
/// order until one returns true.
///
/// This method exposes the `pushRoute` notification from
/// [SystemChannels.navigation].
Future<bool> didPushRoute(String route) => new Future<bool>.value(false);
/// Called when the application's dimensions change. For example,
/// when a phone is rotated.
///
/// This method exposes notifications from [Window.onMetricsChanged].
///
/// ## Sample code
///
/// This [StatefulWidget] implements the parts of the [State] and
......@@ -154,6 +162,8 @@ abstract class WidgetsBindingObserver {
/// preferences, and it should affect all of the text sizes in the
/// application.
///
/// This method exposes notifications from [Window.onTextScaleFactorChanged].
///
/// ## Sample code
///
/// ```dart
......@@ -200,6 +210,8 @@ abstract class WidgetsBindingObserver {
/// Called when the system tells the app that the user's locale has
/// changed. For example, if the user changes the system language
/// settings.
///
/// This method exposes notifications from [Window.onLocaleChanged].
void didChangeLocale(Locale locale) { }
/// Called when the system puts the app in the background or returns
......@@ -207,9 +219,14 @@ abstract class WidgetsBindingObserver {
///
/// An example of implementing this method is provided in the class-level
/// documentation for the [WidgetsBindingObserver] class.
///
/// This method exposes notifications from [SystemChannels.lifecycle].
void didChangeAppLifecycleState(AppLifecycleState state) { }
/// Called when the system is running low on memory.
///
/// This method exposes the `memoryPressure` notification from
/// [SystemChannels.system].
void didHaveMemoryPressure() { }
}
......@@ -359,6 +376,9 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
/// Notify all the observers that the locale has changed (using
/// [WidgetsBindingObserver.didChangeLocale]), giving them the
/// `locale` argument.
///
/// This is called by [handleLocaleChanged] when the [Window.onLocaleChanged]
/// notification is received.
void dispatchLocaleChanged(Locale locale) {
for (WidgetsBindingObserver observer in _observers)
observer.didChangeLocale(locale);
......@@ -367,14 +387,17 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
/// Called when the system pops the current route.
///
/// This first notifies the binding observers (using
/// [WidgetsBindingObserver.didPopRoute]), in registration order,
/// until one returns true, meaning that it was able to handle the
/// request (e.g. by closing a dialog box). If none return true,
/// then the application is shut down.
/// [WidgetsBindingObserver.didPopRoute]), in registration order, until one
/// returns true, meaning that it was able to handle the request (e.g. by
/// closing a dialog box). If none return true, then the application is shut
/// down by calling [SystemNavigator.pop].
///
/// [WidgetsApp] uses this in conjunction with a [Navigator] to
/// cause the back button to close dialog boxes, return from modal
/// pages, and so forth.
///
/// This method exposes the `popRoute` notification from
/// [SystemChannels.navigation].
Future<Null> handlePopRoute() async {
for (WidgetsBindingObserver observer in new List<WidgetsBindingObserver>.from(_observers)) {
if (await observer.didPopRoute())
......@@ -385,6 +408,14 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
/// Called when the host tells the app to push a new route onto the
/// navigator.
///
/// This notifies the binding observers (using
/// [WidgetsBindingObserver.didPushRoute]), in registration order, until one
/// returns true, meaning that it was able to handle the request (e.g. by
/// opening a dialog box). If none return true, then nothing happens.
///
/// This method exposes the `pushRoute` notification from
/// [SystemChannels.navigation].
Future<Null> handlePushRoute(String route) async {
for (WidgetsBindingObserver observer in new List<WidgetsBindingObserver>.from(_observers)) {
if (await observer.didPushRoute(route))
......@@ -406,6 +437,8 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
///
/// Notifies all the observers using
/// [WidgetsBindingObserver.didChangeAppLifecycleState].
///
/// This method exposes notifications from [SystemChannels.lifecycle].
void handleAppLifecycleStateChanged(AppLifecycleState state) {
for (WidgetsBindingObserver observer in _observers)
observer.didChangeAppLifecycleState(state);
......@@ -429,12 +462,26 @@ abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererB
return null;
}
Future<dynamic> _handleSystemMessage(Map<String, dynamic> message) async {
final String type = message['type'];
if (type == 'memoryPressure') {
/// Called when the operating system notifies the application of a memory
/// pressure situation.
///
/// Notifies all the observers using
/// [WidgetsBindingObserver.didHaveMemoryPressure].
///
/// This method exposes the `memoryPressure` notification from
/// [SystemChannels.system].
void handleMemoryPressure() {
for (WidgetsBindingObserver observer in _observers)
observer.didHaveMemoryPressure();
}
Future<dynamic> _handleSystemMessage(Map<String, dynamic> message) async {
final String type = message['type'];
switch (type) {
case 'memoryPressure':
handleMemoryPressure();
break;
}
return null;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment