// Copyright 2015 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.viewsv1;

using fuchsia.sys;

// A view tree is a top-level container for a hierarchy of views.
// Each view is intended to operate independently from others and will
// generally correspond to discrete interactive spaces such as separate
// displays or isolated environments in a multi-user system.
//
// Within a view tree, certain global invariants may be enforced such as
// ensuring that only one view has focus at a time.
//
// View trees will typically be created by system components responsible
// for managing the overall user interface rather than end-user applications.
//
// LIFECYCLE
//
// Use |ViewManager.CreateViewTree()| to create a view tree.  The client
// uses the |ViewTree| interface to manage the view tree's content
// and implements the |ViewTreeListener| interface to handle events.
//
// To destroy a view tree, simply close the |ViewTree| channel.
//
// SETTING A ROOT VIEW
//
// Use |GetContainer()| to obtain an interface for manipulating the root view.
//
// See |ViewContainer| for more information.
//
// GETTING SERVICES
//
// The view tree's |fuchsia::sys::ServiceProvider| offers access to many services
// which are not directly expressed by the |ViewTree| interface itself, such
// as input, accessiblity, and editing capabilities.
//
// For example, perform the following actions to dispatch input events:
//
// 1. Call |GetServiceProvider()| to obtain the view's service provider.
//
// 2. Ask the service provider for its |InputDispatcher|.
//
// 3. Send input events to the dispatcher for delivery to views.
interface ViewTree {
    // Gets the view tree's token.
    GetToken() -> (ViewTreeToken token);

    // Gets a service provider to access services which are associated with
    // the view tree such as input, accessibility and editing capabilities.
    // The view tree service provider is private to the view tree and should
    // not be shared with anyone else.
    //
    // See |InputDispatcher|.
    GetServiceProvider(request<fuchsia.sys.ServiceProvider> service_provider);

    // Gets an interface for managing the view tree's root.
    GetContainer(request<ViewContainer> container);
};

// An interface clients may implement to receive events from a view tree.
interface ViewTreeListener {
    // There are currently no events defined but we have preserved the
    // plumbing for the future when ViewContainer will merge into ViewTree
    // along with its listener.
};