blob: 650ae1fe5983b0b51edc3e279062b7e6023dfdf3 [file] [log] [blame]
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
part of dart_ui;
/// Signature of callbacks that have no arguments and return no data.
typedef void VoidCallback();
/// Signature for [Window.onBeginFrame].
typedef void FrameCallback(Duration duration);
/// Signature for [Window.onPointerDataPacket].
typedef void PointerDataPacketCallback(PointerDataPacket packet);
/// Signature for [Window.onSemanticsAction].
typedef void SemanticsActionCallback(int id, SemanticsAction action);
/// Signature for responses to platform messages.
///
/// Used as a parameter to [Window.sendPlatformMessage] and
/// [Window.onPlatformMessage].
typedef void PlatformMessageResponseCallback(ByteData data);
/// Signature for [Window.onPlatformMessage].
typedef void PlatformMessageCallback(String name, ByteData data, PlatformMessageResponseCallback callback);
/// States that an application can be in.
enum AppLifecycleState {
/// The application is not currently visible to the user. When the
/// application is in this state, the engine will not call the
/// [onBeginFrame] callback.
paused,
/// The application is visible to the user.
resumed,
}
/// A representation of distances for each of the four edges of a rectangle,
/// used to encode the padding that applications should place around their user
/// interface, as exposed by [Window.padding].
///
/// For a generic class that represents distances around a rectangle, see the
/// [EdgeDims] class.
class WindowPadding {
const WindowPadding._({ this.left, this.top, this.right, this.bottom });
/// The distance from the left edge to the first unobscured pixel, in physical pixels.
final double left;
/// The distance from the top edge to the first unobscured pixel, in physical pixels.
final double top;
/// The distance from the right edge to the first unobscured pixel, in physical pixels.
final double right;
/// The distance from the bottom edge to the first unobscured pixel, in physical pixels.
final double bottom;
/// A window padding that has zeros for each edge.
static const WindowPadding zero = const WindowPadding._(left: 0.0, top: 0.0, right: 0.0, bottom: 0.0);
}
/// An identifier used to select a user's language and formatting preferences,
/// consisting of a language and a country. This is a subset of locale
/// identifiers as defined by BCP 47.
class Locale {
/// Creates a new Locale object. The first argument is the
/// primary language subtag, the second is the region subtag.
///
/// For example:
///
/// const Locale swissFrench = const Locale('fr', 'CH');
/// const Locale canadianFrench = const Locale('fr', 'CA');
const Locale(this.languageCode, this.countryCode);
/// The primary language subtag for the locale.
final String languageCode;
/// The region subtag for the locale.
final String countryCode;
bool operator ==(dynamic other) {
if (identical(this, other))
return true;
if (other is! Locale)
return false;
final Locale typedOther = other;
return languageCode == typedOther.languageCode
&& countryCode == typedOther.countryCode;
}
int get hashCode {
int result = 373;
result = 37 * result + languageCode.hashCode;
result = 37 * result + countryCode.hashCode;
return result;
}
String toString() => '${languageCode}_$countryCode';
}
/// The most basic interface to the host operating system's user interface.
///
/// There is a single Window instance in the system, which you can
/// obtain from the [window] property.
class Window {
Window._();
/// The number of device pixels for each logical pixel. This number might not
/// be a power of two. Indeed, it might not even be an integer. For example,
/// the Nexus 6 has a device pixel ratio of 3.5.
double get devicePixelRatio => _devicePixelRatio;
double _devicePixelRatio = 1.0;
/// The dimensions of the rectangle into which the application will be drawn,
/// in physical pixels.
Size get physicalSize => _physicalSize;
Size _physicalSize = Size.zero;
/// The number of physical pixels on each side of the display rectangle into
/// which the application can render, but over which the operating system will
/// likely place system UI (such as the Android system notification area), or
/// which might be rendered outside of the physical display (e.g. overscan
/// regions on television screens).
WindowPadding get padding => _padding;
WindowPadding _padding = WindowPadding.zero;
/// A callback that is invoked whenever the [devicePixelRatio],
/// [physicalSize], or [padding] values change.
VoidCallback onMetricsChanged;
/// The system-reported locale.
///
/// This establishes the language and formatting conventions that application
/// should, if possible, use to render their user interface.
///
/// The [onLocaleChanged] callback is called whenever this value changes.
Locale get locale => _locale;
Locale _locale;
/// A callback that is invoked whenever [locale] changes value.
VoidCallback onLocaleChanged;
/// A callback that is invoked to notify the application that it is an
/// appropriate time to provide a scene using the [SceneBuilder] API and the
/// [render] method. When possible, this is driven by the hardware VSync
/// signal. This is only called if [scheduleFrame] has been called since the
/// last time this callback was invoked.
FrameCallback onBeginFrame;
/// A callback that is invoked when pointer data is available.
PointerDataPacketCallback onPointerDataPacket;
/// The route or path that the operating system requested when the application
/// was launched.
String get defaultRouteName => _defaultRouteName;
String _defaultRouteName;
/// Requests that, at the next appropriate opportunity, the [onBeginFrame]
/// callback be invoked.
void scheduleFrame() native "Window_scheduleFrame";
/// Updates the application's rendering on the GPU with the newly provided
/// [Scene]. This function must be called within the scope of the
/// [onBeginFrame] callback being invoked. If this function is called multiple
/// times during a single [onBeginFrame] callback or called outside the scope
/// of an [onBeginFrame], the call will be ignored.
///
/// To record graphical operations, first create a
/// [PictureRecorder], then construct a [Canvas], passing that
/// [PictureRecorder] to its constructor. After issuing all the
/// graphical operations, call the [endRecording] function on the
/// [PictureRecorder] to obtain the final [Picture] that represents
/// the issued graphical operations.
///
/// Next, create a [SceneBuilder], and add the [Picture] to it using
/// [SceneBuilder.addPicture]. With the [SceneBuilder.build] method
/// you can then obtain a [Scene] object, which you can display to
/// the user via this [render] function.
void render(Scene scene) native "Window_render";
/// Whether the user has requested that [updateSemantics] be called when
/// the semantic contents of window changes.
///
/// The [onSemanticsEnabledChanged] callback is called whenever this value
/// changes.
bool get semanticsEnabled => _semanticsEnabled;
bool _semanticsEnabled = false;
/// A callback that is invoked when the value of [semanticsEnabled] changes.
VoidCallback onSemanticsEnabledChanged;
/// A callback that is invoked whenever the user requests an action to be
/// performed.
///
/// This callback is used when the user expresses the action they wish to
/// perform based on the semantics supplied by [updateSemantics].
SemanticsActionCallback onSemanticsAction;
/// Change the retained semantics data about this window.
///
/// If [semanticsEnabled] is true, the user has requested that this funciton
/// be called whenever the semantic content of this window changes.
///
/// In either case, this function disposes the given update, which means the
/// semantics update cannot be used further.
void updateSemantics(SemanticsUpdate update) native "Window_updateSemantics";
/// Sends a message to a platform-specific plugin.
///
/// The `name` parameter determines which plugin receives the message. The
/// `data` parameter contains the message payload and is typically UTF-8
/// encoded JSON but can be arbitrary data. If the plugin replies to the
/// message, `callback` will be called with the response.
void sendPlatformMessage(String name,
ByteData data,
PlatformMessageResponseCallback callback) {
_sendPlatformMessage(name, callback, data);
}
void _sendPlatformMessage(String name,
PlatformMessageResponseCallback callback,
ByteData data) native "Window_sendPlatformMessage";
/// Called whenever this window receives a message from a platform-specific
/// plugin.
///
/// The `name` parameter determines which plugin sent the message. The `data`
/// parameter is the payload and is typically UTF-8 encoded JSON but can be
/// 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
/// the callback.
PlatformMessageCallback onPlatformMessage;
/// Called by [_dispatchPlatformMessage].
void _respondToPlatformMessage(int responseId, ByteData data)
native "Window_respondToPlatformMessage";
}
/// The [Window] singleton. This object exposes the size of the display, the
/// core scheduler API, the input event callback, the graphics drawing API, and
/// other such core services.
final Window window = new Window._();