protocol/webos-surface-group.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="webos_surface_group">

  <copyright>
    Copyright (c) 2014-2019 LG Electronics, Inc.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

    SPDX-License-Identifier: Apache-2.0
  </copyright>

  <interface name="wl_webos_surface_group_compositor" version="1">
    <description summary="a way to group multi client surfaces together">
      A surface group is a mechanism to group surfaces together that are
      not part of the same client, hence transiency, nor subsurfaces will
      fit the bill. However the compositor will treat surfaces belonging
      to a group very similarly as to surfaces that are transient.

      The group will be controlled by the process that creates it. The group
      will have a root surface and the grouped surfaces will be added as
      layers on top or below it. The creator of the group will designate a z order
      and a name for each layer. Other processes wanting to add their
      surface into the group need to know the both the name of the group and
      the name of the layer.

      A group can allow anonymous surfaces to be attached to them as well.

      Practical suggestion, the name of the group should match the appId of
      parent surface.
    </description>

    <request name="create_surface_group">
      <description summary="creates a group">
        The group will be identified by the 'name' parameter. If a group already
        exists with the given name an error will be reported to the client.
      </description>
      <arg name="id" type="new_id" interface="wl_webos_surface_group"/>
      <arg name="parent" type="object" interface="wl_surface"/>
      <arg name="name" type="string"/>
    </request>

    <request name="get_surface_group">
      <description summary="return an existing surface group">
        A handle to an existing group.
      </description>
      <arg name="id" type="new_id" interface="wl_webos_surface_group"/>
      <arg name="name" type="string"/>
    </request>

  </interface>

  <interface name="wl_webos_surface_group" version="1">
    <request name="create_layer">
      <description summary="creates a layer inside a group">
        The layer will be identified by the 'name' parameter. The compositor
        will place the layer in the given z-index relative to the root layer.
        If negative z-indecies are provided they will be placed underneath the
        root surface accordingly

        The creator will get a handle 'wl_webos_surface_group_layer' to the
        newly created group. The handle can be used to manipulate the layer.

        If a layer group already exists with the given parameters an error
        will be reported to the client.
      </description>
      <arg name="id" type="new_id" interface="wl_webos_surface_group_layer"/>
      <arg name="name" type="string"/>
      <arg name="z_index" type="int"/>
    </request>

    <request name="attach">
      <description summary="attaches a surface to a named group and layer">
        Processes that want to attach a surface to an existing group and layer
        will call this function.

        An error will be reported if either the group, the layer or the layer
        already has a surface attached to it.
      </description>
      <arg name="surface" type="object" interface="wl_surface"/>
      <arg name="layer_name" type="string"/>
    </request>

    <enum name="z_hint">
      <description summary="hint for the z position of the anonymous surfaces">
        The position of anonymous layer is always relative to the root element
        and the named layers in this group.

        If there are multiple entries with the same index designator they will
        get positioned in the order of which they get attached.
      </description>
      <entry name="below" value="0" summary="below the root surface and the lowest named layer"/>
      <entry name="above" value="1" summary="above the root surface and above the highest named layer"/>
      <entry name="top" value="2" summary="above all of the anonymous surfaces"/>
    </enum>

    <request name="attach_anonymous">
      <description summary="tries to attach an anonymous surface to a named group">
        Clients that have a "multi-purpose" surface that might apply to many use
        cases can try to attach their surface to a named group. The group controls
        if that is allowed or not.

        An error will be reported if the group is not available or it does not
        allow anonymous surfaces
      </description>
      <arg name="surface" type="object" interface="wl_surface"/>
      <arg name="z_hint" type="uint" summary="the z index hint"/>
    </request>

    <request name="allow_anonymous_layers">
      <description summary="allow anonymous layers to this group">
        Anonymous layers are layers that do not belong to any named layer.
        They do not enjoy the same benefits as named layers. Their actucal
        z-index might change if there are named layers or a z index of a
        named layer is updated.
      </description>
      <arg name="allow" type="uint" summary="a boolean to indicate if anonymous layers are accepted"/>
    </request>

    <request name="detach">
      <description summary="detaches a surface from this group">
        When a client detaches from a group the compositor will treat is as any other surface.
        In practice this means that if the client does not want the surface to appear "dangling"
        or visible in recents the client should hide/destroy the surface, then detach it from
        the group to avoid any unwanted behavior.
      </description>
      <arg name="surface" type="object" interface="wl_surface"/>
    </request>

    <request name="focus_owner">
      <description summary="transfers keyboard focus to group owner surface">
        Using "focus_owner" a surface-group-client or a surface-group-owner can transfer
        keybord-focus to surface-group-owner.
      </description>
    </request>

    <request name="focus_layer">
      <description summary="transfers keyboard focus to surface attached to layer">
        Using "focus_layer" a surface-group-owner or a surface-group-client can transfer
        keybord-focus to specific surface-group-client attached to surface-group-layer "layer".
      </description>
      <arg name="layer" type="string"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy object">
        Destroys the surface group object.
      </description>
    </request>

    <event name="owner_destroyed">
      <description summary="sent to clients attached to this group">
        If the owner crashes or normally destroys this group the attached
        client will receive this notification.

        Since compositor does not know what to do with client surface still
        attached to this group it will not show them. A well behaving client
        will 'detach' from this group and release its assosicated resource
      </description>
    </event>

  </interface>

  <interface name="wl_webos_surface_group_layer" version="1">
    <description summary="the handle for the group owner to manipulate the layer">
      The handle can be used to change the z order of a particular layer
    </description>

    <request name="set_z_index">
      <description summary="update the z-index">
        Updates the z index for this layer. The compositor will move the surface
        attached to this layer accordingly. If no surface is attached to this
        layer nothing will happen
      </description>
      <arg name="z_index" type="int"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy object">
        Destroys the surface group layer object.
      </description>
    </request>

    <event name="surface_attached">
      <description summary="notify surface-group-owner that surface is attached to this layer">
        When any surafce is attached to this layer, the compositor needs to
        notify surface-group-owner.
      </description>
    </event>

    <event name="surface_detached">
      <description summary="notify surface-group-owner that surface is detached from this layer">
        When any surafce is detached from this layer, the compositor needs to
        notify surface-group-owner. This will be usefull if surface attached to this layer
        is destroyed by associated surface-group-client.
      </description>
    </event>

  </interface>

</protocol>