components/mus/public/interfaces/window_tree.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.

module mus.mojom;

import "components/mus/public/interfaces/compositor_frame.mojom";
import "components/mus/public/interfaces/cursor.mojom";
import "components/mus/public/interfaces/input_events.mojom";
import "components/mus/public/interfaces/mus_constants.mojom";
import "components/mus/public/interfaces/surface_id.mojom";
import "components/mus/public/interfaces/window_manager_constants.mojom";
import "ui/mojo/geometry/geometry.mojom";
import "ui/mojo/ime/text_input_state.mojom";

struct ViewportMetrics {
  mojo.Size size_in_pixels;
  // A value of 0 indicates the real value is not yet available.
  float device_pixel_ratio = 0.0;
};

struct WindowData {
  uint32 parent_id;
  uint32 window_id;
  mojo.Rect bounds;
  map<string, array<uint8>> properties;
  // True if this window is visible. The window may not be drawn on screen (see
  // drawn for specifics).
  bool visible;
  // True if this window is drawn on screen. A window is drawn if attached to
  // the root and all ancestors (including this window) are visible.
  bool drawn;
  ViewportMetrics viewport_metrics;
};

enum ErrorCode {
  NONE,
  VALUE_IN_USE,
  ILLEGAL_ARGUMENT,
};

// Each Window has support for two surfaces. Generally the |DEFAULT| surface
// is used. The |UNDERLAY| surface is useful if the owner of a window wants to
// to Embed() another client and at the same time draw something under the
// embedded apps representation.
enum SurfaceType {
  // Only the owner of a window may obtain this surface.
  // The window manager can change the offset of this by way of
  // SetUnderlaySurfaceOffsetAndExtendedHitArea().
  UNDERLAY,

  // Only the embedded app may obtain this surface. If an app is not embedded
  // in the Window than the owner may also render to this surface as well.
  DEFAULT,
};

// Windows 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 window is identified with a connection id of 0, and value of 1.
//
// Most functions to the WindowTree take a change_id parameter. When
// WindowTree completes processing of a function WindowTree calls
// WindowTreeClient::OnChangeCompleted() with the change_id supplied by the
// client and the result of the function. This allows the client to track
// whether the call succeeded or not. Calls are done via the client interface
// rather than a callback to ensure ordering. The server does not interpret the
// change id in anyway, it is up to the client to assign a value and use it.
// Generally the change id is an ever increasing integer.
interface WindowTree {
  const int32 kAccessPolicyDefault = 0;

  // An embed root has the following abilities:
  // . The app sees all the descendants of the window the app is ebmedded at,
  //   even those from separate connections.
  // . The app is able to Embed() in all the descendants of the window the app
  //   is embedded at, even those from separate connections.
  // Only connections originating from the WindowTreeHostFactory can grant
  // this policy.
  const int32 kAccessPolicyEmbedRoot = 1;

  // Creates a new window 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 |window_id|) must
  // match that of the connection.
  // Errors:
  //   ERROR_CODE_VALUE_IN_USE: a window already exists with the specified id.
  //   ERROR_CODE_ILLEGAL_ARGUMENT: The connection part of |window_id| does not
  //     match the connection id of the client.
  NewWindow(uint32 change_id,
            uint32 window_id,
            map<string, array<uint8>>? properties);

  // Requests the WindowManager to create a new top level window. On success
  // OnTopLevelCreated() is called with the WindowData for the new window. On
  // failure OnChangeCompleted() is called.
  // TODO(sky): this likely needs context, maybe in |properties|.
  NewTopLevelWindow(uint32 change_id,
                    uint32 window_id,
                    map<string, array<uint8>> properties);

  // Deletes a window. This does not recurse. No hierarchy change notifications
  // are sent as a result of this. Only the connection that created the window
  // can delete it.
  DeleteWindow(uint32 change_id, uint32 window_id);

  // Sets the specified bounds of the specified window.
  SetWindowBounds(uint32 change_id, uint32 window_id, mojo.Rect bounds);

  // Sets the client area of the specified window. The client area is specified
  // by way of insets. Everything outside of the insets, and not in
  // |additional_client_areas| is considered non-client area.
  // TODO(sky): convert additional_client_areas to a path.
  SetClientArea(uint32 window_id,
                mojo.Insets insets,
                array<mojo.Rect>? additional_client_areas);

  // Sets the visibility of the specified window to |visible|. Connections are
  // allowed to change the visibility of any window they have created, as well
  // as any of their roots.
  SetWindowVisibility(uint32 change_id, uint32 window_id, bool visible);

  // Sets an individual named property. Setting an individual property to null
  // deletes the property.
  SetWindowProperty(uint32 change_id,
                    uint32 window_id,
                    string name,
                    array<uint8>? value);

  // Attaches a Surface to a particular window.
  AttachSurface(uint32 window_id,
                SurfaceType type,
                Surface& surface,
                SurfaceClient client);

  // Reparents a window.
  // This fails for any of the following reasons:
  // . |parent| or |child| does not identify a valid window.
  // . |child| is an ancestor of |parent|.
  // . |child| is already a child of |parent|.
  //
  // This may result in a connection getting OnWindowDeleted(). See
  // RemoveWindowFromParent for details.
  AddWindow(uint32 change_id, uint32 parent, uint32 child);

  // Removes a window from its current parent. This fails if the window is not
  // valid or the window already has no parent.
  //
  // Removing a window from a parent may result in OnWindowDeleted() being sent
  // to other connections. For example, connection A has windows 1 and 2, with 2
  // a child of 1. Connection B has a root 1. If 2 is removed from 1 then B gets
  // OnWindowDeleted(). This is done as window 2 is effectively no longer
  // visible to connection B.
  RemoveWindowFromParent(uint32 change_id, uint32 window_id);

  // Ties the lifetime of |child| to the lifetime of |parent|. This also
  // places |child| always on top of |parent|.
  // This fails for any of the following reasons:
  // . |window_id| or |transient_window_id| does not identify a valid window.
  // . |transient_window_id| is an ancestor of |window_id|.
  AddTransientWindow(uint32 change_id,
                     uint32 window_id,
                     uint32 transient_window_id);

  // Decouples the lifetime of |transient_window_id| from its transient parent.
  // This does not change transient window's position in the window hierarchy.
  RemoveTransientWindowFromParent(uint32 change_id, uint32 transient_window_id);

  // Reorders a window in its parent, relative to |relative_window_id| according
  // to |direction|. Only the connection that created the window's parent can
  // reorder its children.
  ReorderWindow(uint32 change_id,
                uint32 window_id,
                uint32 relative_window_id,
                OrderDirection direction);

  // Returns the windows comprising the tree starting at |window_id|.
  // |window_id| is the first result in the return value, unless |window_id| is
  // invalid, in which case an empty vector is returned. The windows are visited
  // using a depth first search (pre-order).
  GetWindowTree(uint32 window_id) => (array<WindowData> windows);

  // A connection may grant access to another connection by way of Embed().
  // Embed() results in the supplied WindowTreeClient being configured with a
  // root window of |window_id|. The supplied WindowTreeClient may create child
  // windows and do other various tree operations (including Embed()), but does
  // not see nor have access to any of the windows above the embed point.
  //
  // The caller must have created |window_id|. If not the request fails and the
  // response is false.
  //
  // When a connection embeds a WindowTreeClient the originating connection no
  // longer has privileges to access or see any of the children of the window.
  // If the window had existing children the children are removed. The one
  // exception is the root connection and any connections with the policy
  // kAccessPolicyEmbedRoot.
  //
  // A window may only have one embedding in it at a time. Subsequent calls to
  // Embed() for the same window result in the currently embedded
  // WindowTreeClient being removed. The embedded app is told this by way of
  // OnUnembed(), which is followed by OnWindowDeleted() (as the connection no
  // longer has access to the window).
  //
  // The embedder can detect when the embedded app disconnects by way of
  // OnEmbeddedAppDisconnected().
  //
  // The callback returns whether the embedding was successful, and if the
  // embedding was successful and the originating connection is an embed root
  // the resulting id of the new connection.
  //
  // policy_bitmask is a bitmask of the kAccessPolicy constants. See them for
  // details.
  Embed(uint32 window_id,
        WindowTreeClient client,
        uint32 policy_bitmask) => (bool success, uint16 connection_id);

  SetFocus(uint32 change_id, uint32 window_id);
  SetCanFocus(uint32 window_id, bool can_focus);

  // Sets the cursor when the pointer is inside |window_id| to a system standard
  // cursor provided by the window manager.
  SetPredefinedCursor(uint32 change_id, uint32 window_id, Cursor cursor_id);

  // TODO(erg): Additional cursor methods. Image based cursors, visibility,
  // and cursor locking.

  // Set text input state for the given window.
  SetWindowTextInputState(uint32 window_id, mojo.TextInputState state);

  // Set the input method editor UI (software keyboard, etc) visibility.
  // If state is non-null, the specified window's text input state is updated.
  // Otherwise the existing state is used.
  SetImeVisibility(uint32 window_id, bool visible, mojo.TextInputState? state);

  // See documentation for WindowTreeClient::OnWindowInputEvent().
  OnWindowInputEventAck(uint32 event_id);

  // See description of WindowManagerInternal for details.
  GetWindowManagerInternalClient(
      associated WindowManagerInternalClient& internal);
};

// Changes to windows are not sent to the connection that originated the
// change. For example, if connection 1 changes the bounds of a window by
// calling SetWindowBounds(), connection 1 does not receive
// OnWindowBoundsChanged().
interface WindowTreeClient {
  // Invoked when the client application has been embedded at |root|.
  // See Embed() on WindowTree for more details. |tree| will be a handle back to
  // the window manager service, unless the connection is to the root connection
  // in which case it will be null.
  OnEmbed(uint16 connection_id,
          WindowData root,
          WindowTree? tree,
          uint32 focused_window,
          uint32 access_policy);

  // Invoked when the application embedded at |window| is disconnected. In other
  // words the embedded app closes the connection to the server. This is called
  // on the connection that created |window| as well as any ancestors that have
  // the embed root policy.
  OnEmbeddedAppDisconnected(uint32 window);

  // Sent when another connection is embedded in the Window this connection was
  // previously embedded in. See Embed() for more information.
  OnUnembed(uint32 window);

  // Called in response to NewTopLevelWindow() successfully completing.
  OnTopLevelCreated(uint32 change_id, WindowData data);

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

  OnClientAreaChanged(uint32 window_id,
                      mojo.Insets new_client_area,
                      array<mojo.Rect> new_additional_client_areas);

  OnTransientWindowAdded(uint32 window_id,
                         uint32 transient_window_id);

  OnTransientWindowRemoved(uint32 window_id,
                           uint32 transient_window_id);

  // Invoked when the viewport metrics for the specified windows have changed.
  // This is only sent for the roots, not for every window, it is expected
  // clients propagate this to the tree.
  // TODO(sky): rather than passing viewportmetrics like this, perhaps each
  // window should know the display it is on, and the viewportmetrics of the
  // display may change.
  OnWindowViewportMetricsChanged(array<uint32> window_ids,
                                 ViewportMetrics old_metrics,
                                 ViewportMetrics new_metrics);

  // Invoked when a change is done to the hierarchy. A value of 0 is used to
  // identify a null window. For example, if the old_parent is NULL, 0 is
  // supplied.
  // |windows| contains any windows that are that the client has not been told
  // about. This is not sent for hierarchy changes of windows not known to this
  // client or not attached to the tree.
  OnWindowHierarchyChanged(uint32 window,
                           uint32 new_parent,
                           uint32 old_parent,
                           array<WindowData> windows);

  // Invoked when the order of windows within a parent changes.
  OnWindowReordered(uint32 window_id,
                    uint32 relative_window_id,
                    OrderDirection direction);

  // Invoked when a window is deleted.
  OnWindowDeleted(uint32 window);

  // Invoked when the visibility of the specified window changes.
  OnWindowVisibilityChanged(uint32 window, bool visible);

  // Invoked when a change to the visibility of |window| or one if it's
  // ancestors is done such that the drawn state changes. This is only invoked
  // for the top most window of a particular connection. For example, if you
  // have the hierarchy: A -> B1 -> B2 (B2 is a child of B1 and B1 a child of
  // A), B1/B2 are from connection 2 and A from connection 1 with all windows
  // visible and drawn and the visiblity of A changes to false, then connection
  // 2 is told the drawn state of B1 has changed (to false), but is not told
  // anything about B2 as it's drawn state can be calculated from that of B1.
  //
  // NOTE: This is not invoked if OnWindowVisibilityChanged() is invoked.
  OnWindowDrawnStateChanged(uint32 window, bool drawn);

  // Invoked when a window property is changed. If this change is a removal,
  // |new_data| is null.
  OnWindowSharedPropertyChanged(uint32 window,
                                string name,
                                array<uint8>? new_data);

  // Invoked when an event is targeted at the specified window. The client must
  // call WindowTree::OnWindowInputEventAck() with the same |event_id| to notify
  // that the event has been processed. The client will not receive farther
  // events until the event is ack'ed.
  OnWindowInputEvent(uint32 event_id, uint32 window, Event event);

  OnWindowFocused(uint32 focused_window_id);

  OnWindowPredefinedCursorChanged(uint32 window_id, Cursor cursor_id);

  // A change initiated from the client has completed. See description of
  // change ids for details.
  OnChangeCompleted(uint32 change_id, bool success);

  // The WindowManager is requesting the specified window to close. If the
  // client allows the change it should delete the window.
  RequestClose(uint32 window_id);

  // See description of WindowManagerInternal for details.
  GetWindowManagerInternal(associated WindowManagerInternal& internal);
};

// WindowManagerInternal is used when a WindowTreeClient attempts to modify
// a property of the embed root. When this happens WindowTree calls the
// appropriate function on WindowManagerInternal. For example, if a
// WindowTreeClient calls SetWindowBounds() on its embed root, WindowTree
// calls WmSetBounds(). WindowManagerInternal can then decide if it wants to
// change the bounds or not.
//
// WindowManagerInternal may only be installed from the connection that created
// a new window tree (see WindowTreeHostFactory).
//
// This interface is only used as an associated interface and is associated
// with WindowTreeClient.
interface WindowManagerInternal {
  // When the WindowManagerInternal completes a request it must call back to
  // WindowManagerInternalClient::WmResponse().
  WmSetBounds(uint32 change_id, uint32 window_id, mojo.Rect bounds);
  WmSetProperty(uint32 change_id,
                uint32 window_id,
                string name,
                array<uint8>? value);
  // Asks the WindowManager to create a new window.
  WmCreateTopLevelWindow(uint32 change_id,
                         map<string, array<uint8>> properties);
};

// This interface is only used as an associated interface and is associated
// with WindowTree.
interface WindowManagerInternalClient {
  // The window manager has completed a request with the specific change id.
  WmResponse(uint32 change_id, bool response);

  // Calls WindowTreeClient::RequestClose() on the embedded app at the
  // specified window.
  WmRequestClose(uint32 window_id);

  // Response from WmCreateTopLevelWindow() informing the client of the id for
  // the new window.
  OnWmCreatedTopLevelWindow(uint32 change_id, uint32 window_id);
};