sdk/fidl/fuchsia.modular/story/story_shell.fidl - fuchsia - Git at Google

 // Copyright 2017 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 library fuchsia.modular;

 using fuchsia.ui.policy;
 using fuchsia.ui.views;

 /// This interface is implemented by a story shell. Dependencies are passed to it
 /// in Initialize() on startup. The story shell is also expected to implement
 /// Lifecycle in order to receive a Terminate() call on teardown.
 ///
 /// In one component instance there can only be one StoryShell service instance.
 /// The view token is sent to the separate View service. This way, the story
 /// shell may be implemented as a flutter component.
 ///
 /// Teardown may occur via the session shell calling StoryController.Stop(), the
 /// sessionmgr being terminated, or by the system shutting down.
 [Discoverable] // Created by story shell applications.
 protocol StoryShell {
     Initialize(StoryShellContext story_shell_context);

     /// Adds a new Surface and its corresponding view to be displayed by the
     /// StoryShell. More context that allows the story shell to decide how
     /// to layout will be added later. Also, interface to influence life cycle and
     /// focus is obviously missing.
     /// `view_connection` the new view and the associated Surface ID.
     /// `surface_info` metadata relating to the Surface.
     [Transitional = "Implement AddSurface3 instead"]
     AddSurface(ViewConnection view_connection, SurfaceInfo surface_info);
     /// DEPRECATED.  For transition purposes only.
     [Transitional = "Implement AddSurface3 instead"]
     AddSurface2(ViewConnection2 view_connection, SurfaceInfo surface_info);
     /// For transition purposes only.
     [Transitional = "Only implement while AddSurface is transitional"]
     AddSurface3(ViewConnection view_connection, SurfaceInfo2 surface_info);

     /// Focuses the surface with surface_id, bringing it to the foreground.
     FocusSurface(string surface_id);

     /// Defocuses the surface with surface_id, dismissing it to the background.
     DefocusSurface(string surface_id) -> ();

     /// Adds a container, with corresponding container layouts to the story.
     /// Optionally provide a parent_id to connect to, if omitted adds the
     /// Container node as the root of a new tree in the Story
     /// DEPRECATED
     [Transitional]
     AddContainer(string containerName, string? parentId,
                  SurfaceRelation relation, // relation of container to parent
                  vector<ContainerLayout> layout,
                  vector<ContainerRelationEntry> relationships,
                  vector<ContainerView> views);
     /// DEPRECATED.  For transition purposes only.
     [Transitional]
     AddContainer2(string containerName, string? parentId,
                   SurfaceRelation relation, // relation of container to parent
                   vector<ContainerLayout> layout,
                   vector<ContainerRelationEntry> relationships,
                   vector<ContainerView2> views);

     /// Notify when a Surface is focused in the story. The focus could be from
     /// a user interaction or requested by the framework through
     /// StoryController#FocusModule.
     /// EXPERIMENTAL
     -> OnSurfaceFocused(string surface_id);

     /// Remove the Surface with surface_id from the StoryShell entirely. This is
     /// final. The Surface is removed from the graph. If necessary, the
     /// associated Surface is defocused. There is no expectation that
     /// DefocusSurface is called before this.
     RemoveSurface(string surface_id);

     /// Reconnect the view in viewConnection.
     ///
     /// Called to reconnect views that have previously been added to the story
     /// shell via addSurface, and then disconnected. A ViewTokenPair is created
     /// and the View token is given to the child view.  The ViewHolder token
     /// is notified if the View is destroyed before it is connected.  Once the
     /// ViewHolder has been created using a Scenic `Session`, the Session will be
     /// notified when the view is available, if it becomes unavailable, or if
     /// it is disconnected.
     /// If a surface with a disconnected view is to be shown again, ReconnectView
     /// is called.
     ///
     /// E.g. called in response to StoryShell calling RequestView().
     [Transitional]
     ReconnectView(ViewConnection view_connection);
     /// DEPRECATED.  For transition purposes only.
     [Transitional]
     ReconnectView2(ViewConnection2 view_connection);

     /// Update the surface
     /// This is called when the intent is to update the surface metadata in the
     /// story graph in place. Any fields, except for the surface_id can be
     /// updated. If no value or null is passed for a field it remains unchanged.
     /// This includes the `view_holder_token` inside the connection.
     ///
     /// E.g called when an intent resolves to a module that is known by the
     /// caller to already be running, to update associated metadata.
     [Transitional = "Implement UpdateSurface3 instead"]
     UpdateSurface(ViewConnection view_connection, SurfaceInfo surface_info);
     /// DEPRECATED.  For transition purposes only.
     [Transitional = "Implement UpdateSurface3 instead"]
     UpdateSurface2(ViewConnection2 view_connection, SurfaceInfo surface_info);
     /// For transition purposes only.
     [Transitional = "Only implement while UpdateSurface is transitional"]
     UpdateSurface3(ViewConnection view_connection, SurfaceInfo2 surface_info);
 };

 /// A pair mapping a surface ID to a view (via `view_holder_token`).
 struct ViewConnection {
     /// The ID for the surface
     string surface_id;

     /// Token for embedding the new view corresponding to the surface.
     fuchsia.ui.views.ViewHolderToken view_holder_token;
 };

 /// DEPRECATED, for transition purposes only.
 struct ViewConnection2 {
     /// The ID for the surface
     string surface_id;

     /// Token for embedding the new view corresponding to the surface.
     fuchsia.ui.views.ViewHolderToken view_holder_token;
 };

 /// Contains metadata for a Surface.
 struct SurfaceInfo {
     /// ID of the view that is parent of this Surface.
     string parent_id;

     /// The relationship between the parent Surface and this new Surface. Used
     /// for layout optimization.
     SurfaceRelation? surface_relation;

     /// Information about the module populates the view.
     ModuleManifest? module_manifest;

     /// How the Surface was generated. By an action internal to the story or by
     /// an external action.
     ModuleSource module_source;
 };

 /// Contains metadata for a Surface.
 table SurfaceInfo2 {
     /// ID of the view that is parent of this Surface.
     1: string parent_id;

     /// The relationship between the parent Surface and this new Surface. Used
     /// for layout optimization.
     2: SurfaceRelation surface_relation;

     /// Information about the module populates the view.
     3: ModuleManifest module_manifest;

     /// How the Surface was generated. By an action internal to the story or by
     /// an external action.
     4: ModuleSource module_source;
 };

 struct ContainerView {
     /// Name by which this container node is referenced in container layout and
     /// surface relationship specifications (cf. container.fidl)
     string node_name;

     /// Token for embedding the new view.  The view is resolved from the intent
     /// corresponding to `node_name`.
     fuchsia.ui.views.ViewHolderToken view_holder_token;
 };

 /// DEPRECATED, for transition purposes only.
 struct ContainerView2 {
     /// Name by which this container node is referenced in container layout and
     /// surface relationship specifications (cf. container.fidl)
     string node_name;

     /// Token for embedding the new view.  The view is resolved from the intent
     /// corresponding to `node_name`.
     fuchsia.ui.views.ViewHolderToken view_holder_token;
 };

 /// This interface provides the StoryShell instance with everything it needs to
 /// know or be able to do about the Story. Not much right now, but we expect this
 /// to increase.
 protocol StoryShellContext {
     /// Requests a Presentation connection from the SessionShell. See
     /// SessionShellPresenationProvider in session_shell.fidl.
     GetPresentation(request<fuchsia.ui.policy.Presentation> request);

     /// Starts watching Story shell's visual state.
     WatchVisualState(StoryVisualStateWatcher watcher);

     /// Gets a Link instance that the story shell can use for persisting metadata.
     GetLink(request<Link> request);

     /// Requests a view for a Surface.
     /// Requests that a view for `surface_id` is provided through
     /// StoryShell.ReconnectView().
     RequestView(string surface_id);

     /// Notification that the Surface is no longer on screen.
     OnSurfaceOffScreen(string surface_id);
 };

 /// Implemented by StoryShell to get notified about visual state changes.
 protocol StoryVisualStateWatcher {
     OnVisualStateChange(StoryVisualState visual_state);
 };

 /// Defines the visual state of the Story shell.
 enum StoryVisualState {
     MINIMIZED = 0;
     MAXIMIZED = 1;
     MAXIMIZED_OVERLAYED = 2;
 };
	// Copyright 2017 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	library fuchsia.modular;

	using fuchsia.ui.policy;
	using fuchsia.ui.views;

	/// This interface is implemented by a story shell. Dependencies are passed to it
	/// in Initialize() on startup. The story shell is also expected to implement
	/// Lifecycle in order to receive a Terminate() call on teardown.
	///
	/// In one component instance there can only be one StoryShell service instance.
	/// The view token is sent to the separate View service. This way, the story
	/// shell may be implemented as a flutter component.
	///
	/// Teardown may occur via the session shell calling StoryController.Stop(), the
	/// sessionmgr being terminated, or by the system shutting down.
	[Discoverable] // Created by story shell applications.
	protocol StoryShell {
	Initialize(StoryShellContext story_shell_context);

	/// Adds a new Surface and its corresponding view to be displayed by the
	/// StoryShell. More context that allows the story shell to decide how
	/// to layout will be added later. Also, interface to influence life cycle and
	/// focus is obviously missing.
	/// `view_connection` the new view and the associated Surface ID.
	/// `surface_info` metadata relating to the Surface.
	[Transitional = "Implement AddSurface3 instead"]
	AddSurface(ViewConnection view_connection, SurfaceInfo surface_info);
	/// DEPRECATED. For transition purposes only.
	[Transitional = "Implement AddSurface3 instead"]
	AddSurface2(ViewConnection2 view_connection, SurfaceInfo surface_info);
	/// For transition purposes only.
	[Transitional = "Only implement while AddSurface is transitional"]
	AddSurface3(ViewConnection view_connection, SurfaceInfo2 surface_info);

	/// Focuses the surface with surface_id, bringing it to the foreground.
	FocusSurface(string surface_id);

	/// Defocuses the surface with surface_id, dismissing it to the background.
	DefocusSurface(string surface_id) -> ();

	/// Adds a container, with corresponding container layouts to the story.
	/// Optionally provide a parent_id to connect to, if omitted adds the
	/// Container node as the root of a new tree in the Story
	/// DEPRECATED
	[Transitional]
	AddContainer(string containerName, string? parentId,
	SurfaceRelation relation, // relation of container to parent
	vector<ContainerLayout> layout,
	vector<ContainerRelationEntry> relationships,
	vector<ContainerView> views);
	/// DEPRECATED. For transition purposes only.
	[Transitional]
	AddContainer2(string containerName, string? parentId,
	SurfaceRelation relation, // relation of container to parent
	vector<ContainerLayout> layout,
	vector<ContainerRelationEntry> relationships,
	vector<ContainerView2> views);

	/// Notify when a Surface is focused in the story. The focus could be from
	/// a user interaction or requested by the framework through
	/// StoryController#FocusModule.
	/// EXPERIMENTAL
	-> OnSurfaceFocused(string surface_id);

	/// Remove the Surface with surface_id from the StoryShell entirely. This is
	/// final. The Surface is removed from the graph. If necessary, the
	/// associated Surface is defocused. There is no expectation that
	/// DefocusSurface is called before this.
	RemoveSurface(string surface_id);

	/// Reconnect the view in viewConnection.
	///
	/// Called to reconnect views that have previously been added to the story
	/// shell via addSurface, and then disconnected. A ViewTokenPair is created
	/// and the View token is given to the child view. The ViewHolder token
	/// is notified if the View is destroyed before it is connected. Once the
	/// ViewHolder has been created using a Scenic `Session`, the Session will be
	/// notified when the view is available, if it becomes unavailable, or if
	/// it is disconnected.
	/// If a surface with a disconnected view is to be shown again, ReconnectView
	/// is called.
	///
	/// E.g. called in response to StoryShell calling RequestView().
	[Transitional]
	ReconnectView(ViewConnection view_connection);
	/// DEPRECATED. For transition purposes only.
	[Transitional]
	ReconnectView2(ViewConnection2 view_connection);

	/// Update the surface
	/// This is called when the intent is to update the surface metadata in the
	/// story graph in place. Any fields, except for the surface_id can be
	/// updated. If no value or null is passed for a field it remains unchanged.
	/// This includes the `view_holder_token` inside the connection.
	///
	/// E.g called when an intent resolves to a module that is known by the
	/// caller to already be running, to update associated metadata.
	[Transitional = "Implement UpdateSurface3 instead"]
	UpdateSurface(ViewConnection view_connection, SurfaceInfo surface_info);
	/// DEPRECATED. For transition purposes only.
	[Transitional = "Implement UpdateSurface3 instead"]
	UpdateSurface2(ViewConnection2 view_connection, SurfaceInfo surface_info);
	/// For transition purposes only.
	[Transitional = "Only implement while UpdateSurface is transitional"]
	UpdateSurface3(ViewConnection view_connection, SurfaceInfo2 surface_info);
	};

	/// A pair mapping a surface ID to a view (via `view_holder_token`).
	struct ViewConnection {
	/// The ID for the surface
	string surface_id;

	/// Token for embedding the new view corresponding to the surface.
	fuchsia.ui.views.ViewHolderToken view_holder_token;
	};

	/// DEPRECATED, for transition purposes only.
	struct ViewConnection2 {
	/// The ID for the surface
	string surface_id;

	/// Token for embedding the new view corresponding to the surface.
	fuchsia.ui.views.ViewHolderToken view_holder_token;
	};

	/// Contains metadata for a Surface.
	struct SurfaceInfo {
	/// ID of the view that is parent of this Surface.
	string parent_id;

	/// The relationship between the parent Surface and this new Surface. Used
	/// for layout optimization.
	SurfaceRelation? surface_relation;

	/// Information about the module populates the view.
	ModuleManifest? module_manifest;

	/// How the Surface was generated. By an action internal to the story or by
	/// an external action.
	ModuleSource module_source;
	};

	/// Contains metadata for a Surface.
	table SurfaceInfo2 {
	/// ID of the view that is parent of this Surface.
	1: string parent_id;

	/// The relationship between the parent Surface and this new Surface. Used
	/// for layout optimization.
	2: SurfaceRelation surface_relation;

	/// Information about the module populates the view.
	3: ModuleManifest module_manifest;

	/// How the Surface was generated. By an action internal to the story or by
	/// an external action.
	4: ModuleSource module_source;
	};

	struct ContainerView {
	/// Name by which this container node is referenced in container layout and
	/// surface relationship specifications (cf. container.fidl)
	string node_name;

	/// Token for embedding the new view. The view is resolved from the intent
	/// corresponding to `node_name`.
	fuchsia.ui.views.ViewHolderToken view_holder_token;
	};

	/// DEPRECATED, for transition purposes only.
	struct ContainerView2 {
	/// Name by which this container node is referenced in container layout and
	/// surface relationship specifications (cf. container.fidl)
	string node_name;

	/// Token for embedding the new view. The view is resolved from the intent
	/// corresponding to `node_name`.
	fuchsia.ui.views.ViewHolderToken view_holder_token;
	};

	/// This interface provides the StoryShell instance with everything it needs to
	/// know or be able to do about the Story. Not much right now, but we expect this
	/// to increase.
	protocol StoryShellContext {
	/// Requests a Presentation connection from the SessionShell. See
	/// SessionShellPresenationProvider in session_shell.fidl.
	GetPresentation(request<fuchsia.ui.policy.Presentation> request);

	/// Starts watching Story shell's visual state.
	WatchVisualState(StoryVisualStateWatcher watcher);

	/// Gets a Link instance that the story shell can use for persisting metadata.
	GetLink(request<Link> request);

	/// Requests a view for a Surface.
	/// Requests that a view for `surface_id` is provided through
	/// StoryShell.ReconnectView().
	RequestView(string surface_id);

	/// Notification that the Surface is no longer on screen.
	OnSurfaceOffScreen(string surface_id);
	};

	/// Implemented by StoryShell to get notified about visual state changes.
	protocol StoryVisualStateWatcher {
	OnVisualStateChange(StoryVisualState visual_state);
	};

	/// Defines the visual state of the Story shell.
	enum StoryVisualState {
	MINIMIZED = 0;
	MAXIMIZED = 1;
	MAXIMIZED_OVERLAYED = 2;
	};