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

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 import "mojo/public/interfaces/application/service_provider.mojom"
   6 import "mojo/services/public/interfaces/geometry/geometry.mojom"
   7 import "mojo/services/public/interfaces/input_events/input_events.mojom"
   8 import "mojo/services/public/interfaces/view_manager/view_manager_constants.mojom"
   9
  10 module mojo {
  11
  12 struct ViewData {
  13   uint32 parent_id;
  14   uint32 view_id;
  15   mojo.Rect bounds;
  16   // TODO(sky): add visible.
  17 };
  18
  19 enum ErrorCode {
  20   NONE,
  21   VALUE_IN_USE,
  22   ILLEGAL_ARGUMENT,
  23 };
  24
  25 // ViewManagerInitService is used to grant an application a connection to the
  26 // ViewManager by embedding it at an approriate View.
  27 interface ViewManagerInitService {
  28   // Embed the application @ |url| at an appropriate View.
  29   // The first time this method is called in the lifetime of a View Manager
  30   // application instance, the "appropriate View" is defined as being the
  31   // service root View.
  32   // Subsequent times, implementation of this method is delegated to the
  33   // application embedded at the service root View. This application is
  34   // typically referred to as the "window manager", and will have a specific
  35   // definition of where within its View hierarchy to embed an unparented URL.
  36   // See ViewManagerService below for more details about |service_provider|.
  37   Embed(string url, ServiceProvider service_provider) => (bool success);
  38 };
  39
  40 // Views are identified by a uint32. The upper 16 bits are the connection id,
  41 // and the lower 16 the id assigned by the client.
  42 //
  43 // The root view is identified with a connection id of 0, and value of 1.
  44 [Client=ViewManagerClient]
  45 interface ViewManagerService {
  46   // Creates a new view with the specified id. It is up to the client to ensure
  47   // the id is unique to the connection (the id need not be globally unique).
  48   // Additionally the connection id (embedded in |view_id|) must match that of
  49   // the connection.
  50   // Errors:
  51   //   ERROR_CODE_VALUE_IN_USE: a view already exists with the specified id.
  52   //   ERROR_CODE_ILLEGAL_ARGUMENT: The connection part of |view_id| does not
  53   //     match the connection id of the client.
  54   CreateView(uint32 view_id) => (ErrorCode error_code);
  55
  56   // Deletes a view. This does not recurse. No hierarchy change notifications
  57   // are sent as a result of this. Only the connection that created the view can
  58   // delete it.
  59   DeleteView(uint32 view_id) => (bool success);
  60
  61   // Sets the specified bounds of the specified view.
  62   SetViewBounds(uint32 view_id, mojo.Rect bounds) => (bool success);
  63
  64   // Sets the visibility of the specified view to |visible|. Connections are
  65   // allowed to change the visibility of any view they have created, as well as
  66   // any of their roots.
  67   SetViewVisibility(uint32 view_id, bool visible) => (bool success);
  68
  69   // Reparents a view.
  70   // This fails for any of the following reasons:
  71   // . |parent| or |child| does not identify a valid view.
  72   // . |child| is an ancestor of |parent|.
  73   // . |child| is already a child of |parent|.
  74   //
  75   // This may result in a connection getting OnViewDeleted(). See
  76   // RemoveViewFromParent for details.
  77   AddView(uint32 parent, uint32 child) => (bool success);
  78
  79   // Removes a view from its current parent. This fails if the view is not
  80   // valid or the view already has no parent.
  81   //
  82   // Removing a view from a parent may result in OnViewDeleted() being sent to
  83   // other connections. For example, connection A has views 1 and 2, with 2 a
  84   // child of 1. Connection B has a root 1. If 2 is removed from 1 then B gets
  85   // OnViewDeleted(). This is done as view 2 is effectively no longer visible to
  86   // connection B.
  87   RemoveViewFromParent(uint32 view_id) => (bool success);
  88
  89   // Reorders a view in its parent, relative to |relative_view_id| according to
  90   // |direction|.
  91   // Only the connection that created the view's parent can reorder its
  92   // children.
  93   ReorderView(uint32 view_id,
  94               uint32 relative_view_id,
  95               OrderDirection direction) => (bool success);
  96
  97   // Returns the views comprising the tree starting at |view_id|. |view_id| is
  98   // the first result in the return value, unless |view_id| is invalid, in which
  99   // case an empty vector is returned. The views are visited using a depth first
 100   // search (pre-order).
 101   GetViewTree(uint32 view_id) => (ViewData[] views);
 102
 103   // Shows the specified image (png encoded) in the specified view.
 104   SetViewContents(uint32 view_id,
 105                   handle<shared_buffer> buffer,
 106                   uint32 buffer_size) => (bool success);
 107
 108   // Embeds the app for |url| in the specified view. More specifically this
 109   // creates a new connection to the specified url, expecting to get a
 110   // ViewManagerClient and configures it with the root view |view|. Fails
 111   // if |view| was not created by this connection.
 112   //
 113   // If a particular client invokes Embed() multiple times with the same url,
 114   // the connection is reused. When this happens the ViewManagerClient is
 115   // notified of the additional roots by way of OnEmbed().
 116   //
 117   // A view may only be a root of one connection at a time. Subsequent calls to
 118   // Embed() for the same view result in the view being removed from the
 119   // current connection. The current connection is told this by way of
 120   // OnViewDeleted().
 121   //
 122   // When a connection embeds an app the connection no longer has priviledges
 123   // to access or see any of the children of the view. If the view had existing
 124   // children the children are removed. The one exception is the root
 125   // connection.
 126   //
 127   // If |view_id| is 0, the View Manager delegates determination of what view to
 128   // embed |url| at to the app embedded at the service root view (i.e. the
 129   // window manager).
 130   //
 131   // |service_provider| encapsulates services offered by the embedder to the
 132   // embedded app alongside this Embed() call. It also provides a means for
 133   // the embedder to connect to services symmetrically exposed by the embedded
 134   // app. Note that if a different app is subsequently embedded at |view_id|
 135   // the |service_provider|'s connection to its client in the embedded app and
 136   // any services it provided are not broken and continue to be valid.
 137   Embed(string url,
 138         uint32 view_id,
 139         ServiceProvider service_provider) => (bool success);
 140
 141   // TODO(sky): move these to a separate interface when FIFO works.
 142
 143   // Sends OnViewInputEvent() to the owner of the specified view.
 144   DispatchOnViewInputEvent(uint32 view_id, mojo.Event event);
 145 };
 146
 147 // Changes to views are not sent to the connection that originated the
 148 // change. For example, if connection 1 changes the bounds of a view by calling
 149 // SetBounds(), connection 1 does not receive OnViewBoundsChanged().
 150 [Client=ViewManagerService]
 151 interface ViewManagerClient {
 152   // Invoked when the client application has been embedded at |root|.
 153   // See Embed() on ViewManagerService for more details.
 154   OnEmbed(uint16 connection_id,
 155           string embedder_url,
 156           ViewData root,
 157           ServiceProvider& service_provider);
 158
 159   // Invoked when a view's bounds have changed.
 160   OnViewBoundsChanged(uint32 view, mojo.Rect old_bounds, mojo.Rect new_bounds);
 161
 162   // Invoked when a change is done to the hierarchy. A value of 0 is used to
 163   // identify a null view. For example, if the old_parent is NULL, 0 is
 164   // supplied.
 165   // |views| contains any views that are that the client has not been told
 166   // about. This is not sent for hierarchy changes of views not known to this
 167   // client or not attached to the tree.
 168   OnViewHierarchyChanged(uint32 view,
 169                          uint32 new_parent,
 170                          uint32 old_parent,
 171                          ViewData[] views);
 172
 173   // Invoked when the order of views within a parent changes.
 174   OnViewReordered(uint32 view_id,
 175                   uint32 relative_view_id,
 176                   OrderDirection direction);
 177
 178   // Invoked when a view is deleted.
 179   OnViewDeleted(uint32 view);
 180
 181   // Invoked when an event is targeted at the specified view.
 182   OnViewInputEvent(uint32 view, mojo.Event event) => ();
 183
 184   // TODO(sky): The following methods represent an interface between the view
 185   //            manager and the application embedded at the service root view
 186   //            (i.e. the window manager). These methods are not called on
 187   //            any other clients. They should be moved to a separate interface
 188   //            once support for derived FIFOs is landed.
 189
 190   // Requests the window manager create a "top level" view embedding |url|.
 191   Embed(string url, ServiceProvider& service_provider);
 192
 193   // Requests the view manager dispatch the event.
 194   DispatchOnViewInputEvent(mojo.Event event);
 195 };
 196
 197 }