mojo/services/public/interfaces/view_manager/view_manager.mojom

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

import "../geometry/geometry.mojom"

module mojo.view_manager {

struct INode {
  uint32 parent_id;
  uint32 node_id;
  uint32 view_id;
  mojo.Rect bounds;
};

// IViewManagerInit is responsible for launching the client that controls the
// root node. mojo::view_manager returns an instance of this. All other
// connections are established by the client this creates.
interface IViewManagerInit {
  // Connects to |url| creating a connection that has the roots |nodes|.
  Connect(string url) => (bool success);
};

// Functions that mutate the hierarchy take a change id. This is an ever
// increasing integer used to identify the change. Every hierarchy change
// increases this value. The server only accepts changes where the supplied
// |server_change_id| matches the expected next value. This ensures changes are
// made in a well defined order.
//
// Nodes and Views are identified by a uint32. The upper 16 bits are the
// connection id, and the lower 16 the id assigned by the client.
//
// The root node is identified with a connection id of 0, and value of 1.
[Client=IViewManagerClient]
interface IViewManager {
  // Creates a new node with the specified id. It is up to the client to ensure
  // the id is unique to the connection (the id need not be globally unique).
  // Additionally the connection id (embedded in |node_id|) must match that of
  // the connection.
  CreateNode(uint32 node_id) => (bool success);

  // Deletes a node. This does not recurse. No hierarchy change notifications
  // are sent as a result of this. Only the connection that created the node can
  // delete it.
  DeleteNode(uint32 node_id) => (bool success);

  // Sets the specified bounds of the specified node.
  SetNodeBounds(uint32 node_id, mojo.Rect bounds) => (bool success);

  // Reparents a node. See description above class for details of |change_id|.
  // This fails for any of the following reasons:
  // . |server_change_id| is not the expected id.
  // . |parent| or |child| does not identify a valid node.
  // . |child| is an ancestor of |parent|.
  // . |child| is already a child of |parent|.
  //
  // This may result in a connection getting OnNodeDeleted(). See
  // RemoveNodeFromParent for details.
  AddNode(uint32 parent,
          uint32 child,
          uint32 server_change_id) => (bool success);

  // Removes a view from its current parent. See description above class for
  // details of |change_id|. This fails if the node is not valid,
  // |server_change_id| doesn't match, or the node already has no parent.
  //
  // Removing a node from a parent may result in OnNodeDeleted() being sent to
  // other connections. For example, connection A has nodes 1 and 2, with 2 a
  // child of 1. Connection B has a root 1. If 2 is removed from 1 then B gets
  // OnNodeDeleted(). This is done as node 2 is effectively no longer visible to
  // connection B.
  RemoveNodeFromParent(uint32 node_id,
                       uint32 server_change_id) => (bool success);

  // Returns the nodes comprising the tree starting at |node_id|. |node_id| is 
  // the first result in the return value, unless |node_id| is invalid, in which
  // case an empty vector is returned. The nodes are visited using a depth first
  // search (pre-order).
  GetNodeTree(uint32 node_id) => (INode[] nodes);

  // Creates a new view with the specified id. It is up to the client to ensure
  // the id is unique to the connection (the id need not be globally unique).
  // Additionally the connection id (embedded in |view_id|) must match that of
  // the connection.
  CreateView(uint32 view_id) => (bool success);

  // Deletes the view with the specified id. Only the connection that created
  // the view can delete it.
  DeleteView(uint32 view_id) => (bool success);

  // Sets the view a node is showing.
  SetView(uint32 node_id, uint32 view_id) => (bool success);

  // Shows the specified image (png encoded) in the specified view.
  SetViewContents(uint32 view_id,
                  handle<shared_buffer> buffer,
                  uint32 buffer_size) => (bool success);

  // Connects to |url| creating a connection that has the roots |nodes|. Fails
  // if |nodes| is empty or contains nodes that were not created by this
  // connection.
  Connect(string url, uint32[] nodes) => (bool success);
};

// Changes to nodes/views are not sent to the connection that originated the
// change. For example, if connection 1 attaches a view to a node (SetView())
// connection 1 does not receive OnNodeViewReplaced().
[Client=IViewManager]
interface IViewManagerClient {
  // Invoked once the connection has been established. |connection_id| is the id
  // that uniquely identifies this connection. |next_server_change_id| is the
  // id of the next change the server is expecting. |nodes| are the nodes
  // parented to the root.
  OnViewManagerConnectionEstablished(uint16 connection_id,
                                     uint32 next_server_change_id,
                                     INode[] nodes);

  // This is sent to clients when a change is made to the server that results
  // in the |server_change_id| changing but the client isn't notified. This is
  // not sent if the client receives a callback giving a new
  // |server_change_id|. For example, if a client 1 changes the hierarchy in
  // some way but client 2 isn't notified of the change, then client 2 gets
  // OnServerChangeIdAdvanced().
  OnServerChangeIdAdvanced(uint32 next_server_change_id);

  // Invoked when a node's bounds have changed.
  OnNodeBoundsChanged(uint32 node, mojo.Rect old_bounds, mojo.Rect new_bounds);

  // Invoked when a change is done to the hierarchy. A value of 0 is used to
  // identify a null node. For example, if the old_parent is NULL, 0 is
  // supplied. See description above ViewManager for details on the change ids.
  // |nodes| contains any nodes that are that the client has not been told
  // about. This is not sent for hierarchy changes of nodes not known to this
  // client or not attached to the tree.
  OnNodeHierarchyChanged(uint32 node,
                         uint32 new_parent,
                         uint32 old_parent,
                         uint32 server_change_id,
                         INode[] nodes);

  // Invoked when a node is deleted.
  OnNodeDeleted(uint32 node, uint32 server_change_id);

  // Invoked when the view associated with a node is replaced by another view.
  // 0 is used to identify a null view.
  OnNodeViewReplaced(uint32 node, uint32 new_view_id, uint32 old_view_id);

  // Invoked when a view is deleted.
  OnViewDeleted(uint32 view);
};

}