sdk/fidl/fuchsia.modular/story/story_command.fidl

// Copyright 2018 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.mem;

// StoryCommands are POD structures that describe the set of operations that
// can be performed on a story by components outside the modular framework. All commands are:
//
//   (1) Scoped to a single story
//   (2) Idempotent: issuing the same command twice yields the same result
//   (3) Symmetrical with observation: the same structures are used to describe
//       operations to watchers of a story (through SessionWatcher) as are used
//       to control a story.
union StoryCommand {
    // Sets the focus state of the story to |set_focus_state.focused|.
    SetFocusState set_focus_state;

    // Adds a Mod.
    AddMod add_mod;

    // Removes an existing Mod.
    RemoveMod remove_mod;

    // Sets the value of a Link.
    SetLinkValue set_link_value;

    // Brings focus to a mod.
    FocusMod focus_mod;

    // Updates the kind_of_proto_story option in a story.
    SetKindOfProtoStoryOption set_kind_of_proto_story_option;
};

struct SetFocusState {
    bool focused;
};

// Adds a mod described by |intent| to the story with name |mod_name|. If
// |mod_name| already exists in the story, the mod is updated.
struct AddMod {
    // The name of the mod within the story. The mod's name acts as the unique
    // ID of the mod, scoped to the story in which it is contained. Since
    // AddMod is reused for observation and mod names are vector<string>
    // inside the framework, they are vector<string> here as well.
    //
    // Clients should treat the full vector as a single opaque value.
    //
    // Clients should provide |mod_name_transitional| instead.
    // If both are provided, |mod_name| is ignored.
    //
    // TODO(MF-148): Convert to string
    vector<string> mod_name;

    // The name of the mod within the story. This should be used instead of
    // |mod_name|. If provided, it is equivalent to passing |mod_name| with
    // a single item. If both are provided, |mod_name| is ignored.
    //
    // TODO(MF-148): Remove
    string? mod_name_transitional;

    Intent intent;

    // |surface_relation| defines the visual relationship between this mod and the
    // mod at |surface_parent_mod_name|.
    SurfaceRelation surface_relation;
    vector<string>? surface_parent_mod_name;
};

// Removes the mod under |mod_name| from the story.
struct RemoveMod {
    // The name of the mod within the story.
    //
    // Clients should provide |mod_name_transitional| instead.
    // If both are provided, |mod_name| is ignored.
    //
    // TODO(MF-148): Convert to string
    vector<string> mod_name;

    // The name of the mod within the story. This should be used instead of
    // |mod_name|. If provided, it is equivalent to passing |mod_name| with
    // a single item. If both are provided, |mod_name| is ignored.
    //
    // TODO(MF-148): Remove
    string? mod_name_transitional;
};

// Sets the value of link at |path| to |value|.
struct SetLinkValue {
    LinkPath path;
    fuchsia.mem.Buffer? value;
};

// Instructs the session shell to focus the mod under |mod_name|.
struct FocusMod {
    // The name of the mod within the story.
    //
    // Clients should provide |mod_name_transitional| instead.
    // If both are provided, |mod_name| is ignored.
    //
    // TODO(MF-148): Convert to string
    vector<string> mod_name;

    // The name of the mod within the story. This should be used instead of
    // |mod_name|. If provided, it is equivalent to passing |mod_name| with
    // a single item. If both are provided, |mod_name| is ignored.
    //
    // TODO(MF-148): Remove
    string? mod_name_transitional;
};

// Updates the kind_of_proto_story option in a story.
struct SetKindOfProtoStoryOption {
    bool value;
};