From ef8ed56fcad1a670cc7e2d131836b334637845f9 Mon Sep 17 00:00:00 2001 From: Tong Mu Date: Wed, 10 Apr 2024 14:00:11 -0700 Subject: [PATCH] embedder API docs --- shell/common/platform_view.h | 22 ++++++++++--------- shell/platform/embedder/embedder.h | 35 +++++++++++++++++++++++++----- 2 files changed, 41 insertions(+), 16 deletions(-) diff --git a/shell/common/platform_view.h b/shell/common/platform_view.h index aa4a8a4768aa7..04f85a5387c1e 100644 --- a/shell/common/platform_view.h +++ b/shell/common/platform_view.h @@ -102,10 +102,9 @@ class PlatformView { /// @param[in] callback The callback that's invoked once the shell /// has attempted to add the view. /// - virtual void OnPlatformViewAddView( - int64_t view_id, - const ViewportMetrics& viewport_metrics, - PlatformView::AddViewCallback callback) = 0; + virtual void OnPlatformViewAddView(int64_t view_id, + const ViewportMetrics& viewport_metrics, + AddViewCallback callback) = 0; /// @brief Deallocate resources for a removed view and inform /// Dart about the removal. @@ -120,9 +119,8 @@ class PlatformView { /// @param[in] callback The callback that's invoked once the shell has /// attempted to remove the view. /// - virtual void OnPlatformViewRemoveView( - int64_t view_id, - PlatformView::RemoveViewCallback callback) = 0; + virtual void OnPlatformViewRemoveView(int64_t view_id, + RemoveViewCallback callback) = 0; //-------------------------------------------------------------------------- /// @brief Notifies the delegate that the specified callback needs to @@ -565,8 +563,10 @@ class PlatformView { /// successful. /// /// This operation is asynchronous; avoid using the view until - /// |callback| returns true. Embedders should prepare resources in - /// advance but be ready to clean up on failure. + /// |callback| returns true. Callers should prepare resources for the + /// view (if any) in advance but be ready to clean up on failure. + /// + /// The callback is called on a different thread. /// /// Do not use for implicit views, which are added internally during /// shell initialization. Adding |kFlutterImplicitViewId| or an @@ -589,9 +589,11 @@ class PlatformView { /// Dart about the removal. Finally, it invokes |callback| with /// whether the operation is successful. /// - /// This operation is asynchronous. Embedders should not deallocate + /// This operation is asynchronous. The embedder should not deallocate /// resources until the |callback| is invoked. /// + /// The callback is called on a different thread. + /// /// Do not use for implicit views, which are never removed throughout /// the lifetime of the app. /// Removing |kFlutterImplicitViewId| or an diff --git a/shell/platform/embedder/embedder.h b/shell/platform/embedder/embedder.h index 702b1d4923043..8fcf6eaa6fb57 100644 --- a/shell/platform/embedder/embedder.h +++ b/shell/platform/embedder/embedder.h @@ -2582,9 +2582,23 @@ FlutterEngineResult FlutterEngineRunInitialized( //------------------------------------------------------------------------------ /// @brief Adds a view. /// -/// This is an asynchronous operation. The view should not be used -/// until the |add_view_callback| is invoked with an `added` of -/// `true`. +/// This operation notifies the engine to allocate resources and +/// inform Dart about the view, and on success, schedules a new +/// frame. Finally, it invokes |info.add_view_callback| with whether +/// the operation is successful. +/// +/// This operation is asynchronous; avoid using the view until +/// |info.add_view_callback| returns true. The embedder should +/// prepare resources in advance but be ready to clean up on +/// failure. +/// +/// The callback is called on a different thread managed by the +/// engine. The embedder must re-thread if needed. +/// +/// Do not use for implicit views, which are added internally during +/// initialization. Adding the implicit view ID or an existing view +/// ID will fail, indicated by |info.add_view_callback| returning +/// false. /// /// @param[in] engine A running engine instance. /// @param[in] info The add view arguments. This can be deallocated @@ -2601,9 +2615,18 @@ FlutterEngineResult FlutterEngineAddView(FLUTTER_API_SYMBOL(FlutterEngine) //------------------------------------------------------------------------------ /// @brief Removes a view. /// -/// This is an asynchronous operation. The view's resources must not -/// be cleaned up until the |remove_view_callback| is invoked with -/// a |removed| value of `true`. +/// This operation notifies the engine to deallocate resources and +/// inform Dart about the removal. Finally, it invokes +/// |info.remove_view_callback| with whether the operation is +/// successful. +/// +/// This operation is asynchronous. The embedder should not +/// deallocate resources until the |callback| is invoked. +/// +/// Do not use for implicit views, which are never removed +/// throughout the lifetime of the app. Removing +/// |kFlutterImplicitViewId| or an non-existent view ID will fail, +/// indicated by |callback| returning false. /// /// @param[in] engine A running engine instance. /// @param[in] info The remove view arguments. This can be deallocated