Flutter Engine
flutter::Engine::Delegate Class Referenceabstract

While the engine operates entirely on the UI task runner, it needs the capabilities of the other components to fulfill the requirements of the root isolate. The shell is the only class that implements this interface as no other component has access to all components in a thread safe manner. The engine delegates these tasks to the shell via this interface. More...

#include <engine.h>

Inheritance diagram for flutter::Engine::Delegate:
flutter::Shell

Public Member Functions

virtual void OnEngineUpdateSemantics (SemanticsNodeUpdates updates, CustomAccessibilityActionUpdates actions)=0
 When the accessibility tree has been updated by the Flutter application, this new information needs to be conveyed to the underlying platform. The engine delegates this task to the shell via this call. The engine cannot access the underlying platform directly because of threading considerations. Most platform specific APIs to convey accessibility information are only safe to access on the platform task runner while the engine is running on the UI task runner. More...
 
virtual void OnEngineHandlePlatformMessage (fml::RefPtr< PlatformMessage > message)=0
 When the Flutter application has a message to send to the underlying platform, the message needs to be forwarded to the platform on the appropriate thread (via the platform task runner). The engine delegates this task to the shell via this method. More...
 
virtual void OnPreEngineRestart ()=0
 Notifies the delegate that the root isolate of the application is about to be discarded and a new isolate with the same runtime started in its place. This should only happen in the Flutter "debug" runtime mode in the cold-restart scenario. The embedder may need to reset native resource in response to the restart. More...
 
virtual void OnRootIsolateCreated ()=0
 Notifies the shell that the root isolate is created. Currently, this information is to add to the service protocol list of available root isolates running in the VM and their names so that the appropriate isolate can be selected in the tools for debugging and instrumentation. More...
 
virtual void UpdateIsolateDescription (const std::string isolate_name, int64_t isolate_port)=0
 Notifies the shell of the name of the root isolate and its port when that isolate is launched, restarted (in the cold-restart scenario) or the application itself updates the name of the root isolate (via PlatformDispatcher.setIsolateDebugName in platform_dispatcher.dart). The name of the isolate is meaningless to the engine but is used in instrumentation and tooling. Currently, this information is to update the service protocol list of available root isolates running in the VM and their names so that the appropriate isolate can be selected in the tools for debugging and instrumentation. More...
 
virtual void SetNeedsReportTimings (bool needs_reporting)=0
 Notifies the shell that the application has an opinion about whether its frame timings need to be reported backed to it. Due to the asynchronous nature of rendering in Flutter, it is not possible for the application to determine the total time it took to render a specific frame. While the layer-tree is constructed on the UI thread, it needs to be rendering on the raster thread. Dart code cannot execute on this thread. So any instrumentation about the frame times gathered on this thread needs to be aggregated and sent back to the UI thread for processing in Dart. More...
 
virtual std::unique_ptr< std::vector< std::string > > ComputePlatformResolvedLocale (const std::vector< std::string > &supported_locale_data)=0
 Directly invokes platform-specific APIs to compute the locale the platform would have natively resolved to. More...
 

Detailed Description

While the engine operates entirely on the UI task runner, it needs the capabilities of the other components to fulfill the requirements of the root isolate. The shell is the only class that implements this interface as no other component has access to all components in a thread safe manner. The engine delegates these tasks to the shell via this interface.

Definition at line 139 of file engine.h.

Member Function Documentation

◆ ComputePlatformResolvedLocale()

virtual std::unique_ptr<std::vector<std::string> > flutter::Engine::Delegate::ComputePlatformResolvedLocale ( const std::vector< std::string > &  supported_locale_data)
pure virtual

Directly invokes platform-specific APIs to compute the locale the platform would have natively resolved to.

Parameters
[in]supported_locale_dataThe vector of strings that represents the locales supported by the app. Each locale consists of three strings: languageCode, countryCode, and scriptCode in that order.
Returns
A vector of 3 strings languageCode, countryCode, and scriptCode that represents the locale selected by the platform. Empty strings mean the value was unassigned. Empty vector represents a null locale.

Referenced by flutter::Engine::ScheduleFrame().

◆ OnEngineHandlePlatformMessage()

virtual void flutter::Engine::Delegate::OnEngineHandlePlatformMessage ( fml::RefPtr< PlatformMessage message)
pure virtual

When the Flutter application has a message to send to the underlying platform, the message needs to be forwarded to the platform on the appropriate thread (via the platform task runner). The engine delegates this task to the shell via this method.

See also
PlatformView::HandlePlatformMessage
Parameters
[in]messageThe message from the Flutter application to send to the underlying platform.

Referenced by flutter::Engine::ScheduleFrame().

◆ OnEngineUpdateSemantics()

virtual void flutter::Engine::Delegate::OnEngineUpdateSemantics ( SemanticsNodeUpdates  updates,
CustomAccessibilityActionUpdates  actions 
)
pure virtual

When the accessibility tree has been updated by the Flutter application, this new information needs to be conveyed to the underlying platform. The engine delegates this task to the shell via this call. The engine cannot access the underlying platform directly because of threading considerations. Most platform specific APIs to convey accessibility information are only safe to access on the platform task runner while the engine is running on the UI task runner.

See also
SemanticsNode, SemticsNodeUpdates, CustomAccessibilityActionUpdates, PlatformView::UpdateSemantics
Parameters
[in]updatesA map with the stable semantics node identifier as key and the node properties as the value.
[in]actionsA map with the stable semantics node identifier as key and the custom node action as the value.

Referenced by flutter::Engine::ScheduleFrame().

◆ OnPreEngineRestart()

virtual void flutter::Engine::Delegate::OnPreEngineRestart ( )
pure virtual

Notifies the delegate that the root isolate of the application is about to be discarded and a new isolate with the same runtime started in its place. This should only happen in the Flutter "debug" runtime mode in the cold-restart scenario. The embedder may need to reset native resource in response to the restart.

See also
PlatformView::OnPreEngineRestart

Referenced by flutter::Engine::Restart().

◆ OnRootIsolateCreated()

virtual void flutter::Engine::Delegate::OnRootIsolateCreated ( )
pure virtual

Notifies the shell that the root isolate is created. Currently, this information is to add to the service protocol list of available root isolates running in the VM and their names so that the appropriate isolate can be selected in the tools for debugging and instrumentation.

Referenced by flutter::Engine::ScheduleFrame().

◆ SetNeedsReportTimings()

virtual void flutter::Engine::Delegate::SetNeedsReportTimings ( bool  needs_reporting)
pure virtual

Notifies the shell that the application has an opinion about whether its frame timings need to be reported backed to it. Due to the asynchronous nature of rendering in Flutter, it is not possible for the application to determine the total time it took to render a specific frame. While the layer-tree is constructed on the UI thread, it needs to be rendering on the raster thread. Dart code cannot execute on this thread. So any instrumentation about the frame times gathered on this thread needs to be aggregated and sent back to the UI thread for processing in Dart.

When the application indicates that frame times need to be reported, it collects this information till a specified number of data points are gathered. Then this information is sent back to Dart code via Engine::ReportTimings.

This option is engine counterpart of the Window._setNeedsReportTimings in window.dart.

Parameters
[in]needs_reportingIf reporting information should be collected and send back to Dart.

Referenced by flutter::Engine::ScheduleFrame().

◆ UpdateIsolateDescription()

virtual void flutter::Engine::Delegate::UpdateIsolateDescription ( const std::string  isolate_name,
int64_t  isolate_port 
)
pure virtual

Notifies the shell of the name of the root isolate and its port when that isolate is launched, restarted (in the cold-restart scenario) or the application itself updates the name of the root isolate (via PlatformDispatcher.setIsolateDebugName in platform_dispatcher.dart). The name of the isolate is meaningless to the engine but is used in instrumentation and tooling. Currently, this information is to update the service protocol list of available root isolates running in the VM and their names so that the appropriate isolate can be selected in the tools for debugging and instrumentation.

Parameters
[in]isolate_nameThe isolate name
[in]isolate_portThe isolate port

Referenced by flutter::Engine::ScheduleFrame().


The documentation for this class was generated from the following file: