blob: 038bd2777e2d4e8baabd4296a8f229b942401e17 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="webos_surface_group">
<copyright>
Copyright (c) 2014-2020 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>
<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>
<request name="destroy" type="destructor">
<description summary="destroy object">
Destroys the surface group object.
</description>
</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>
</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>