blob: bfe9f7485ee47955d788311eb4d605c0f315b629 [file] [log] [blame]
// 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) -> ();
/// 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);
/// 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;
/// Collection of user-defined key-value attributes that describe this surface (module).
///
/// The `Annotation.value` field of each `Annotation` is always set.
5: vector<Annotation>:MAX_ANNOTATIONS_PER_MODULE annotations;
/// The view ref associated with the surface, if one is present.
6: fuchsia.ui.views.ViewRef view_ref;
};
/// 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);
/// Requests a view for a Surface.
/// Requests that a view for `surface_id` is provided through
/// StoryShell.ReconnectView().
RequestView(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;
};