// Copyright 2019 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.ui.remotewidgets;

using fuchsia.fonts;

/// Defines special actions that are used on Values to control QuickUi
/// navigation or provide extra semantics to actions associated with them.
enum QuickAction {
    /// Can be set on a button spec. Tells the client to navigate to a details
    /// view reserved exclusively for specs from this server.
    DETAILS = 0x80000000;
    /// Can be set on a button spec. Tells the client to return to the previous
    /// view and discard any changes in flight.
    CANCEL = 0x40000000;
    /// Can be set on a button spec. Tells the client to return to the previous
    /// view and send all changes in flight to the server.
    SUBMIT = 0x20000000;
    /// Can be set on a text spec used in a ListValue. Tells the client to
    /// consider the associated list item as selected.
    SELECT = 0x10000000;
};

/// The value to hold these numeric types.
union Number {
    1: int64 int_value;
    2: uint64 uint_value;
    3: float64 double_value;
};

/// Represents a number type in a ui spec with an associated action.
struct NumberValue {
    Number value;
    int32 action = 0;
};

/// Represents a string type in a ui spec with an associated action.
struct TextValue {
    string:64 text;
    int32 action = 0;
};

/// Represents a button type in a ui spec with an associated action.
struct ButtonValue {
    string:64 label;
    int32 action = 0;
};

/// Represents a progress indicator type in a ui spec with an associated action.
struct ProgressValue {
    // [0..1] inclusive.
    float32 value;
    int32 action = 0;
};

/// Represents an input type in a ui spec with an associated action.
struct InputValue {
    string:1024 text;
    // 0 = multiline. 1 = Default.
    int32 lines = 1;
    int32 action = 0;
};

/// Represents an icon type in a ui spec with an associated action.
struct IconValue {
    int32 code_point;
    fuchsia.fonts.FamilyName? font_family;
    int32 action = 0;
};

/// Represents a grid of strings type in a ui spec with an associated action.
struct GridValue {
    byte columns;
    vector<TextValue>:256 values;
};

/// Represents a list of strings type in a ui spec.
struct ListValue {
    bool multiselect = false;
    bool popup = false;
    string:128 title;
    vector<TextValue>:1024 items;
};

/// Represents a graph type in a ui spec with an associated action.
struct GraphValue {
    // [0..1] inclusive.
    float32 value;
    // Unit of progress in the x-axis.
    int32 step;
    int32 action = 0;
};

/// Represents a Value that is union of all types.
union Value {
    1: NumberValue number;
    2: TextValue text;
    3: ProgressValue progress;
    4: ButtonValue button;
    5: InputValue input;
    6: IconValue icon;
    7: GridValue grid;
    8: GraphValue graph;
    9: ListValue list;
};

/// Represents a group of [Value]s with a title.
table Group {
    // The title to show for this group.
    1: string:128 title;
    // The icon to show for this spec.
    2: IconValue icon;
    // List of [Value] objects that form part of this spec.
    3: vector<Value>:16 values;
};

/// Describes a specification of quick UI.
table Spec {
    // The title to show for this spec.
    1: string:128 title;
    // List of [Group] objects that form part of this spec.
    2: vector<Group>:8 groups;
};

/// Defines a protocol for a component to provide specs for building UI for
/// quick settings or notifications, independent of any platform.
[Discoverable]
protocol QuickUi {
    /// Request [Spec] from the provider. The provider should return Spec
    /// whenever it is ready to. Until then this request remains outstanding,
    /// aka "hanging get". The provider can return completely different set of
    /// status on every invocation. The client can provide an optional [Value]
    /// to allow the provider to customize the returned UI spec. Typically,
    /// this value was part of previous [Spec] and identifies the part of
    /// [Spec] the user interacted with.
    GetSpec(Value? value) -> (Spec spec);
};