blob: 03db7f1d608ca38c4a9af7c98c226d2eedc8f1fc [file] [log] [blame]
// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'dart:io' show Platform;
import 'dart:ui' as ui show FlutterView, Scene, SceneBuilder, SemanticsUpdate;
import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart';
import 'binding.dart';
import 'box.dart';
import 'debug.dart';
import 'layer.dart';
import 'object.dart';
/// The layout constraints for the root render object.
@immutable
class ViewConfiguration {
/// Creates a view configuration.
///
/// By default, the view has zero [size] and a [devicePixelRatio] of 1.0.
const ViewConfiguration({
this.size = Size.zero,
this.devicePixelRatio = 1.0,
});
/// The size of the output surface.
final Size size;
/// The pixel density of the output surface.
final double devicePixelRatio;
/// Creates a transformation matrix that applies the [devicePixelRatio].
///
/// The matrix translates points from the local coordinate system of the
/// app (in logical pixels) to the global coordinate system of the
/// [FlutterView] (in physical pixels).
Matrix4 toMatrix() {
return Matrix4.diagonal3Values(devicePixelRatio, devicePixelRatio, 1.0);
}
@override
bool operator ==(Object other) {
if (other.runtimeType != runtimeType) {
return false;
}
return other is ViewConfiguration
&& other.size == size
&& other.devicePixelRatio == devicePixelRatio;
}
@override
int get hashCode => Object.hash(size, devicePixelRatio);
@override
String toString() => '$size at ${debugFormatDouble(devicePixelRatio)}x';
}
/// The root of the render tree.
///
/// The view represents the total output surface of the render tree and handles
/// bootstrapping the rendering pipeline. The view has a unique child
/// [RenderBox], which is required to fill the entire output surface.
class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox> {
/// Creates the root of the render tree.
///
/// Typically created by the binding (e.g., [RendererBinding]).
///
/// Providing a [configuration] is optional, but a configuration must be set
/// before calling [prepareInitialFrame]. This decouples creating the
/// [RenderView] object from configuring it. Typically, the object is created
/// by the [View] widget and configured by the [RendererBinding] when the
/// [RenderView] is registered with it by the [View] widget.
RenderView({
RenderBox? child,
ViewConfiguration? configuration,
required ui.FlutterView view,
}) : _configuration = configuration,
_view = view {
this.child = child;
}
/// The current layout size of the view.
Size get size => _size;
Size _size = Size.zero;
/// The constraints used for the root layout.
///
/// Typically, this configuration is set by the [RendererBinding], when the
/// [RenderView] is registered with it. It will also update the configuration
/// if necessary. Therefore, if used in conjunction with the [RendererBinding]
/// this property must not be set manually as the [RendererBinding] will just
/// override it.
///
/// For tests that want to change the size of the view, set
/// [TestFlutterView.physicalSize] on the appropriate [TestFlutterView]
/// (typically [WidgetTester.view]) instead of setting a configuration
/// directly on the [RenderView].
ViewConfiguration get configuration => _configuration!;
ViewConfiguration? _configuration;
set configuration(ViewConfiguration value) {
if (_configuration == value) {
return;
}
final ViewConfiguration? oldConfiguration = _configuration;
_configuration = value;
if (_rootTransform == null) {
// [prepareInitialFrame] has not been called yet, nothing to do for now.
return;
}
if (oldConfiguration?.toMatrix() != configuration.toMatrix()) {
replaceRootLayer(_updateMatricesAndCreateNewRootLayer());
}
assert(_rootTransform != null);
markNeedsLayout();
}
/// Whether a [configuration] has been set.
bool get hasConfiguration => _configuration != null;
/// The [FlutterView] into which this [RenderView] will render.
ui.FlutterView get flutterView => _view;
final ui.FlutterView _view;
/// Whether Flutter should automatically compute the desired system UI.
///
/// When this setting is enabled, Flutter will hit-test the layer tree at the
/// top and bottom of the screen on each frame looking for an
/// [AnnotatedRegionLayer] with an instance of a [SystemUiOverlayStyle]. The
/// hit-test result from the top of the screen provides the status bar settings
/// and the hit-test result from the bottom of the screen provides the system
/// nav bar settings.
///
/// If there is no [AnnotatedRegionLayer] on the bottom, the hit-test result
/// from the top provides the system nav bar settings. If there is no
/// [AnnotatedRegionLayer] on the top, the hit-test result from the bottom
/// provides the system status bar settings.
///
/// Setting this to false does not cause previous automatic adjustments to be
/// reset, nor does setting it to true cause the app to update immediately.
///
/// If you want to imperatively set the system ui style instead, it is
/// recommended that [automaticSystemUiAdjustment] is set to false.
///
/// See also:
///
/// * [AnnotatedRegion], for placing [SystemUiOverlayStyle] in the layer tree.
/// * [SystemChrome.setSystemUIOverlayStyle], for imperatively setting the system ui style.
bool automaticSystemUiAdjustment = true;
/// Bootstrap the rendering pipeline by preparing the first frame.
///
/// This should only be called once, and must be called before changing
/// [configuration]. It is typically called immediately after calling the
/// constructor.
///
/// This does not actually schedule the first frame. Call
/// [PipelineOwner.requestVisualUpdate] on [owner] to do that.
void prepareInitialFrame() {
assert(owner != null);
assert(_rootTransform == null);
scheduleInitialLayout();
scheduleInitialPaint(_updateMatricesAndCreateNewRootLayer());
assert(_rootTransform != null);
}
Matrix4? _rootTransform;
TransformLayer _updateMatricesAndCreateNewRootLayer() {
_rootTransform = configuration.toMatrix();
final TransformLayer rootLayer = TransformLayer(transform: _rootTransform);
rootLayer.attach(this);
assert(_rootTransform != null);
return rootLayer;
}
// We never call layout() on this class, so this should never get
// checked. (This class is laid out using scheduleInitialLayout().)
@override
void debugAssertDoesMeetConstraints() { assert(false); }
@override
void performResize() {
assert(false);
}
@override
void performLayout() {
assert(_rootTransform != null);
_size = configuration.size;
assert(_size.isFinite);
if (child != null) {
child!.layout(BoxConstraints.tight(_size));
}
}
/// Determines the set of render objects located at the given position.
///
/// Returns true if the given point is contained in this render object or one
/// of its descendants. Adds any render objects that contain the point to the
/// given hit test result.
///
/// The [position] argument is in the coordinate system of the render view,
/// which is to say, in logical pixels. This is not necessarily the same
/// coordinate system as that expected by the root [Layer], which will
/// normally be in physical (device) pixels.
bool hitTest(HitTestResult result, { required Offset position }) {
if (child != null) {
child!.hitTest(BoxHitTestResult.wrap(result), position: position);
}
result.add(HitTestEntry(this));
return true;
}
@override
bool get isRepaintBoundary => true;
@override
void paint(PaintingContext context, Offset offset) {
if (child != null) {
context.paintChild(child!, offset);
}
assert(() {
final List<DebugPaintCallback> localCallbacks = _debugPaintCallbacks.toList();
for (final DebugPaintCallback paintCallback in localCallbacks) {
if (_debugPaintCallbacks.contains(paintCallback)) {
paintCallback(context, offset, this);
}
}
return true;
}());
}
@override
void applyPaintTransform(RenderBox child, Matrix4 transform) {
assert(_rootTransform != null);
transform.multiply(_rootTransform!);
super.applyPaintTransform(child, transform);
}
/// Uploads the composited layer tree to the engine.
///
/// Actually causes the output of the rendering pipeline to appear on screen.
void compositeFrame() {
if (!kReleaseMode) {
FlutterTimeline.startSync('COMPOSITING');
}
try {
final ui.SceneBuilder builder = ui.SceneBuilder();
final ui.Scene scene = layer!.buildScene(builder);
if (automaticSystemUiAdjustment) {
_updateSystemChrome();
}
_view.render(scene);
scene.dispose();
assert(() {
if (debugRepaintRainbowEnabled || debugRepaintTextRainbowEnabled) {
debugCurrentRepaintColor = debugCurrentRepaintColor.withHue((debugCurrentRepaintColor.hue + 2.0) % 360.0);
}
return true;
}());
} finally {
if (!kReleaseMode) {
FlutterTimeline.finishSync();
}
}
}
/// Sends the provided [SemanticsUpdate] to the [FlutterView] associated with
/// this [RenderView].
///
/// A [SemanticsUpdate] is produced by a [SemanticsOwner] during the
/// [EnginePhase.flushSemantics] phase.
void updateSemantics(ui.SemanticsUpdate update) {
_view.updateSemantics(update);
}
void _updateSystemChrome() {
// Take overlay style from the place where a system status bar and system
// navigation bar are placed to update system style overlay.
// The center of the system navigation bar and the center of the status bar
// are used to get SystemUiOverlayStyle's to update system overlay appearance.
//
// Horizontal center of the screen
// V
// ++++++++++++++++++++++++++
// | |
// | System status bar | <- Vertical center of the status bar
// | |
// ++++++++++++++++++++++++++
// | |
// | Content |
// ~ ~
// | |
// ++++++++++++++++++++++++++
// | |
// | System navigation bar | <- Vertical center of the navigation bar
// | |
// ++++++++++++++++++++++++++ <- bounds.bottom
final Rect bounds = paintBounds;
// Center of the status bar
final Offset top = Offset(
// Horizontal center of the screen
bounds.center.dx,
// The vertical center of the system status bar. The system status bar
// height is kept as top window padding.
_view.padding.top / 2.0,
);
// Center of the navigation bar
final Offset bottom = Offset(
// Horizontal center of the screen
bounds.center.dx,
// Vertical center of the system navigation bar. The system navigation bar
// height is kept as bottom window padding. The "1" needs to be subtracted
// from the bottom because available pixels are in (0..bottom) range.
// I.e. for a device with 1920 height, bound.bottom is 1920, but the most
// bottom drawn pixel is at 1919 position.
bounds.bottom - 1.0 - _view.padding.bottom / 2.0,
);
final SystemUiOverlayStyle? upperOverlayStyle = layer!.find<SystemUiOverlayStyle>(top);
// Only android has a customizable system navigation bar.
SystemUiOverlayStyle? lowerOverlayStyle;
switch (defaultTargetPlatform) {
case TargetPlatform.android:
lowerOverlayStyle = layer!.find<SystemUiOverlayStyle>(bottom);
case TargetPlatform.fuchsia:
case TargetPlatform.iOS:
case TargetPlatform.linux:
case TargetPlatform.macOS:
case TargetPlatform.windows:
break;
}
// If there are no overlay style in the UI don't bother updating.
if (upperOverlayStyle == null && lowerOverlayStyle == null) {
return;
}
// If both are not null, the upper provides the status bar properties and the lower provides
// the system navigation bar properties. This is done for advanced use cases where a widget
// on the top (for instance an app bar) will create an annotated region to set the status bar
// style and another widget on the bottom will create an annotated region to set the system
// navigation bar style.
if (upperOverlayStyle != null && lowerOverlayStyle != null) {
final SystemUiOverlayStyle overlayStyle = SystemUiOverlayStyle(
statusBarBrightness: upperOverlayStyle.statusBarBrightness,
statusBarIconBrightness: upperOverlayStyle.statusBarIconBrightness,
statusBarColor: upperOverlayStyle.statusBarColor,
systemStatusBarContrastEnforced: upperOverlayStyle.systemStatusBarContrastEnforced,
systemNavigationBarColor: lowerOverlayStyle.systemNavigationBarColor,
systemNavigationBarDividerColor: lowerOverlayStyle.systemNavigationBarDividerColor,
systemNavigationBarIconBrightness: lowerOverlayStyle.systemNavigationBarIconBrightness,
systemNavigationBarContrastEnforced: lowerOverlayStyle.systemNavigationBarContrastEnforced,
);
SystemChrome.setSystemUIOverlayStyle(overlayStyle);
return;
}
// If only one of the upper or the lower overlay style is not null, it provides all properties.
// This is done for developer convenience as it allows setting both status bar style and
// navigation bar style using only one annotated region layer (for instance the one
// automatically created by an [AppBar]).
final bool isAndroid = defaultTargetPlatform == TargetPlatform.android;
final SystemUiOverlayStyle definedOverlayStyle = (upperOverlayStyle ?? lowerOverlayStyle)!;
final SystemUiOverlayStyle overlayStyle = SystemUiOverlayStyle(
statusBarBrightness: definedOverlayStyle.statusBarBrightness,
statusBarIconBrightness: definedOverlayStyle.statusBarIconBrightness,
statusBarColor: definedOverlayStyle.statusBarColor,
systemStatusBarContrastEnforced: definedOverlayStyle.systemStatusBarContrastEnforced,
systemNavigationBarColor: isAndroid ? definedOverlayStyle.systemNavigationBarColor : null,
systemNavigationBarDividerColor: isAndroid ? definedOverlayStyle.systemNavigationBarDividerColor : null,
systemNavigationBarIconBrightness: isAndroid ? definedOverlayStyle.systemNavigationBarIconBrightness : null,
systemNavigationBarContrastEnforced: isAndroid ? definedOverlayStyle.systemNavigationBarContrastEnforced : null,
);
SystemChrome.setSystemUIOverlayStyle(overlayStyle);
}
@override
Rect get paintBounds => Offset.zero & (size * configuration.devicePixelRatio);
@override
Rect get semanticBounds {
assert(_rootTransform != null);
return MatrixUtils.transformRect(_rootTransform!, Offset.zero & size);
}
@override
void debugFillProperties(DiagnosticPropertiesBuilder properties) {
// call to ${super.debugFillProperties(description)} is omitted because the
// root superclasses don't include any interesting information for this
// class
assert(() {
properties.add(DiagnosticsNode.message('debug mode enabled - ${kIsWeb ? 'Web' : Platform.operatingSystem}'));
return true;
}());
properties.add(DiagnosticsProperty<Size>('view size', _view.physicalSize, tooltip: 'in physical pixels'));
properties.add(DoubleProperty('device pixel ratio', _view.devicePixelRatio, tooltip: 'physical pixels per logical pixel'));
properties.add(DiagnosticsProperty<ViewConfiguration>('configuration', configuration, tooltip: 'in logical pixels'));
if (_view.platformDispatcher.semanticsEnabled) {
properties.add(DiagnosticsNode.message('semantics enabled'));
}
}
static final List<DebugPaintCallback> _debugPaintCallbacks = <DebugPaintCallback>[];
/// Registers a [DebugPaintCallback] that is called every time a [RenderView]
/// repaints in debug mode.
///
/// The callback may paint a debug overlay on top of the content of the
/// [RenderView] provided to the callback. Callbacks are invoked in the
/// order they were registered in.
///
/// Neither registering a callback nor the continued presence of a callback
/// changes how often [RenderView]s are repainted. It is up to the owner of
/// the callback to call [markNeedsPaint] on any [RenderView] for which it
/// wants to update the painted overlay.
///
/// Does nothing in release mode.
static void debugAddPaintCallback(DebugPaintCallback callback) {
assert(() {
_debugPaintCallbacks.add(callback);
return true;
}());
}
/// Removes a callback registered with [debugAddPaintCallback].
///
/// It does not schedule a frame to repaint the [RenderView]s without the
/// overlay painted by the removed callback. It is up to the owner of the
/// callback to call [markNeedsPaint] on the relevant [RenderView]s to
/// repaint them without the overlay.
///
/// Does nothing in release mode.
static void debugRemovePaintCallback(DebugPaintCallback callback) {
assert(() {
_debugPaintCallbacks.remove(callback);
return true;
}());
}
}
/// A callback for painting a debug overlay on top of the provided [RenderView].
///
/// Used by [RenderView.debugAddPaintCallback] and
/// [RenderView.debugRemovePaintCallback].
typedef DebugPaintCallback = void Function(PaintingContext context, Offset offset, RenderView renderView);