From a12cafee5939c8b6032cd193fc43667b886f3243 Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Thu, 19 Oct 2017 17:30:30 -0700 Subject: [PATCH] Documentation improvements - RTL and others (flutter/engine#4248) --- engine/src/flutter/lib/ui/text.dart | 83 +++++++++++++++++++ engine/src/flutter/lib/ui/window.dart | 2 +- .../ios/framework/Headers/FlutterCodecs.h | 2 +- 3 files changed, 85 insertions(+), 2 deletions(-) diff --git a/engine/src/flutter/lib/ui/text.dart b/engine/src/flutter/lib/ui/text.dart index 3418a285250..57ee8cad744 100644 --- a/engine/src/flutter/lib/ui/text.dart +++ b/engine/src/flutter/lib/ui/text.dart @@ -559,6 +559,89 @@ class ParagraphStyle { } /// A direction in which text flows. +/// +/// Some languages are written from the left to the right (for example, English, +/// Tamil, or Chinese), while others are written from the right to the left (for +/// example Aramaic, Hebrew, or Urdu). Some are also written in a mixture, for +/// example Arabic is mostly written right-to-left, with numerals written +/// left-to-right. +/// +/// The text direction must be provided to APIs that render text or lay out +/// boxes horizontally, so that they can determine which direction to start in: +/// either right-to-left, [TextDirection.rtl]; or left-to-right, +/// [TextDirection.ltr]. +/// +/// ## Design discussion +/// +/// Flutter is designed to address the needs of applications written in any of +/// the world's currently-used languages, whether they use a right-to-left or +/// left-to-right writing direction. Flutter does not support other writing +/// modes, such as vertical text or boustrophedon text, as these are rarely used +/// in computer programs. +/// +/// It is common when developing user interface frameworks to pick a default +/// text direction — typically left-to-right, the direction most familiar to the +/// engineers working on the framework — because this simplifies the development +/// of applications on the platform. Unfortunately, this frequently results in +/// the platform having unexpected left-to-right biases or assumptions, as +/// engineers will typically miss places where they need to support +/// right-to-left text. This then results in bugs that only manifest in +/// right-to-left environments. +/// +/// In an effort to minimize the extent to which Flutter experiences this +/// category of issues, the lowest levels of the Flutter framework do not have a +/// default text reading direction. Any time a reading direction is necessary, +/// for example when text is to be displayed, or when a +/// writing-direction-dependent value is to be interpreted, the reading +/// direction must be explicitly specified. Where possible, such as in `switch` +/// statements, the right-to-left case is listed first, to avoid the impression +/// that it is an afterthought. +/// +/// At the higher levels (specifically starting at the widgets library), an +/// ambient [Directionality] is introduced, which provides a default. Thus, for +/// instance, a [Text] widget in the scope of a [MaterialApp] widget does not +/// need to be given an explicit writing direction. The [Directionality.of] +/// static method can be used to obtain the ambient text direction for a +/// particular [BuildContext]. +/// +/// ### Known left-to-right biases in Flutter +/// +/// Despite the design intent described above, certain left-to-right biases have +/// nonetheless crept into Flutter's design. These include: +/// +/// * The [Canvas] origin is at the top left, and the x-axis increases in a +/// left-to-right direction. +/// +/// * The default localization in the widgets and material libraries is +/// American English, which is left-to-right. +/// +/// ### Visual properties vs directional properties +/// +/// Many classes in the Flutter framework are offered in two versions, a +/// visually-oriented variant, and a text-direction-dependent variant. For +/// example, [EdgeInsets] is described in terms of top, left, right, and bottom, +/// while [EdgeInsetsDirectional] is described in terms of top, start, end, and +/// bottom, where start and end correspond to right and left in right-to-left +/// text and left and right in left-to-right text. +/// +/// There are distinct use cases for each of these variants. +/// +/// Text-direction-dependent variants are useful when developing user interfaces +/// that should "flip" with the text direction. For example, a paragraph of text +/// in English will typically be left-aligned and a quote will be indented from +/// the left, while in Arabic it will be right-aligned and indented from the +/// right. Both of these cases are described by the direction-dependent +/// [TextAlign.start] and [EdgeInsetsDirectional.start]. +/// +/// In contrast, the visual variants are useful when the text direction is known +/// and not affected by the reading direction. For example, an application +/// giving driving directions might show a "turn left" arrow on the left and a +/// "turn right" arrow on the right — and would do so whether the application +/// was localized to French (left-to-right) or Hebrew (right-to-left). +/// +/// In practice, it is also expected that many developers will only be +/// targeting one language, and in that case it may be simpler to think in +/// visual terms. // The order of this enum must match the order of the values in TextDirection.h's TextDirection. enum TextDirection { /// The text flows from right to left (e.g. Arabic, Hebrew). diff --git a/engine/src/flutter/lib/ui/window.dart b/engine/src/flutter/lib/ui/window.dart index 421368cba7c..a5351eec949 100644 --- a/engine/src/flutter/lib/ui/window.dart +++ b/engine/src/flutter/lib/ui/window.dart @@ -470,7 +470,7 @@ class Window { /// arbitrary data. /// /// Message handlers must call the function given in the `callback` parameter. - /// If the handler does not need to respond, the handler should pass `null` to + /// If the handler does not need to respond, the handler should pass null to /// the callback. /// /// The framework invokes this callback in the same zone in which the diff --git a/engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterCodecs.h b/engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterCodecs.h index 89b7e66d147..0d191db90b1 100644 --- a/engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterCodecs.h +++ b/engine/src/flutter/shell/platform/darwin/ios/framework/Headers/FlutterCodecs.h @@ -99,7 +99,7 @@ FLUTTER_EXPORT On the Dart side, these values are represented as follows: - - `nil` or `NSNull`: `null` + - `nil` or `NSNull`: null - `NSNumber`: `bool`, `int`, or `double`, depending on the contained value. - `FlutterStandardBigInteger`: `int` - `NSString`: `String`