mirror of
https://gitlab.freedesktop.org/wayland/wayland-protocols.git
synced 2025-12-20 07:00:08 +01:00
Merge branch 'ext-toplevel-placement' into 'main'
Draft: ext-toplevel-placement-v1: new protocol See merge request wayland/wayland-protocols!389
This commit is contained in:
probonopd
commit
234f56d9af
2 changed files with 146 additions and 0 deletions
|
|
@ -59,6 +59,7 @@ staging_protocols = {
|
||||||
'ext-image-capture-source': ['v1'],
|
'ext-image-capture-source': ['v1'],
|
||||||
'ext-image-copy-capture': ['v1'],
|
'ext-image-copy-capture': ['v1'],
|
||||||
'ext-session-lock': ['v1'],
|
'ext-session-lock': ['v1'],
|
||||||
|
'ext-toplevel-placement': ['v1'],
|
||||||
'ext-transient-seat': ['v1'],
|
'ext-transient-seat': ['v1'],
|
||||||
'ext-workspace': ['v1'],
|
'ext-workspace': ['v1'],
|
||||||
'fifo': ['v1'],
|
'fifo': ['v1'],
|
||||||
|
|
|
||||||
145
staging/ext-toplevel-placement/ext-toplevel-placement-v1.xml
Normal file
145
staging/ext-toplevel-placement/ext-toplevel-placement-v1.xml
Normal file
|
|
@ -0,0 +1,145 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<protocol name="ext_toplevel_placement_v1">
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
Copyright © 2025 The Wayland Authors
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a
|
||||||
|
copy of this software and associated documentation files (the "Software"),
|
||||||
|
to deal in the Software without restriction, including without limitation
|
||||||
|
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||||
|
and/or sell copies of the Software, and to permit persons to whom the
|
||||||
|
Software is furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice (including the next
|
||||||
|
paragraph) shall be included in all copies or substantial portions of the
|
||||||
|
Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||||
|
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||||
|
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||||
|
DEALINGS IN THE SOFTWARE.
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<interface name="ext_toplevel_placement_manager_v1" version="1">
|
||||||
|
<description summary="manager to create placement suggestion objects">
|
||||||
|
This interface is a manager used to create placement suggestion objects
|
||||||
|
for xdg_toplevels.
|
||||||
|
|
||||||
|
The compositor may choose to restrict the availability of this manager
|
||||||
|
based on its internal policy. This might involve checking the client's
|
||||||
|
identity (e.g., via app_id or executable path) against a list of trusted
|
||||||
|
clients configurable by the user.
|
||||||
|
|
||||||
|
</description>
|
||||||
|
|
||||||
|
<request name="destroy" type="destructor">
|
||||||
|
<description summary="destroy the placement manager"/>
|
||||||
|
</request>
|
||||||
|
|
||||||
|
<request name="get_placement">
|
||||||
|
<description summary="get the placement suggestion interface for a toplevel">
|
||||||
|
Attempt to create an ext_toplevel_placement_v1 interface for a given
|
||||||
|
xdg_toplevel.
|
||||||
|
|
||||||
|
If the toplevel already has a placement object,
|
||||||
|
the compositor MUST send the `placement_exists` error.
|
||||||
|
|
||||||
|
This interface can only be obtained once per xdg_toplevel.
|
||||||
|
</description>
|
||||||
|
<arg name="id" type="new_id" interface="ext_toplevel_placement_v1"/>
|
||||||
|
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
|
||||||
|
</request>
|
||||||
|
|
||||||
|
<enum name="error">
|
||||||
|
<entry name="placement_exists" value="0"
|
||||||
|
summary="the toplevel already has a placement object"/>
|
||||||
|
</enum>
|
||||||
|
</interface>
|
||||||
|
|
||||||
|
<interface name="ext_toplevel_placement_v1" version="1">
|
||||||
|
<description summary="Interface for suggesting absolute toplevel placement">
|
||||||
|
This interface allows trusted clients to suggest an initial placement
|
||||||
|
position for its associated xdg_toplevel window, specified using absolute logical
|
||||||
|
coordinates relative to a specific xdg_output.
|
||||||
|
|
||||||
|
Access to create and use this interface is subject to compositor policy.
|
||||||
|
|
||||||
|
The suggested placement is only a hint. The compositor retains full
|
||||||
|
authority to determine the final window position. Clients must
|
||||||
|
monitor configure events to determine the actual final placement.
|
||||||
|
</description>
|
||||||
|
|
||||||
|
<request name="destroy" type="destructor">
|
||||||
|
<description summary="destroy the placement suggestion object"/>
|
||||||
|
</request>
|
||||||
|
|
||||||
|
<request name="suggest_position">
|
||||||
|
<description summary="suggest placement at absolute logical coordinates on an output">
|
||||||
|
Suggests an initial placement position (x, y) for the associated xdg_toplevel.
|
||||||
|
The coordinates are in logical pixels, relative to the top-left corner
|
||||||
|
of the specified xdg_output's logical area.
|
||||||
|
|
||||||
|
This request serves as a hint to the compositor. The compositor MAY ignore
|
||||||
|
this hint entirely or modify the outcome based on its state or policies.
|
||||||
|
The client MUST NOT assume the suggestion will be honored precisely.
|
||||||
|
|
||||||
|
This suggestion is primarily intended for *initial* placement and should
|
||||||
|
ideally be sent before the first wl_surface.commit that maps the window.
|
||||||
|
Compositors are unlikely to substantially alter placement based on
|
||||||
|
suggestions sent after the window is already mapped and positioned.
|
||||||
|
|
||||||
|
This request causes the compositor to send `placement_state`, including
|
||||||
|
the output and logical coordinates where the toplevel is currently placed,
|
||||||
|
or `not_placed`.
|
||||||
|
</description>
|
||||||
|
<arg name="output" type="object" interface="xdg_output" summary="target output"/>
|
||||||
|
<arg name="x" type="int" summary="suggested logical x coordinate relative to output"/>
|
||||||
|
<arg name="y" type="int" summary="suggested logical y coordinate relative to output"/>
|
||||||
|
</request>
|
||||||
|
|
||||||
|
<request name="get_placement_state">
|
||||||
|
<description summary="request the current placement state">
|
||||||
|
Requests the compositor to send the current placement state, including
|
||||||
|
the output and logical coordinates where the toplevel is currently placed.
|
||||||
|
</description>
|
||||||
|
</request>
|
||||||
|
|
||||||
|
<event name="placement_state">
|
||||||
|
<description summary="notify client of current placement state">
|
||||||
|
This event notifies the client of the output and logical position where
|
||||||
|
the compositor has actually placed the window, typically sent during
|
||||||
|
the initial configuration sequence after considering any placement
|
||||||
|
suggestions, and in response to a `get_placement_state` request.
|
||||||
|
|
||||||
|
This allows the client to know the result of its suggestion and update
|
||||||
|
its stored state accurately. Compositors are not required to send this
|
||||||
|
event if no suggestion was made or considered relevant to the final
|
||||||
|
placement decision.
|
||||||
|
|
||||||
|
Standard xdg_toplevel.configure events remain the primary source for
|
||||||
|
ongoing size, state, and potentially position updates.
|
||||||
|
</description>
|
||||||
|
<arg name="output" type="object" interface="xdg_output" summary="output the window is currently placed on"/>
|
||||||
|
<arg name="x" type="int" summary="current logical x coordinate relative to output"/>
|
||||||
|
<arg name="y" type="int" summary="current logical y coordinate relative to output"/>
|
||||||
|
</event>
|
||||||
|
|
||||||
|
<event name="not_placed">
|
||||||
|
<description summary="notify client that placement based on suggestion definitively failed">
|
||||||
|
This event is sent if the compositor *cannot* place the toplevel window
|
||||||
|
*as suggested*. This might be due to various reasons like no suitable output,
|
||||||
|
geometry conflicts, or unresolvable policy restrictions *after considering the suggestion*.
|
||||||
|
Receiving this event implies that the compositor will *not* honor the
|
||||||
|
placement suggestion and the toplevel might not be placed at all, or will be
|
||||||
|
placed using a fallback mechanism unrelated to the suggestion.
|
||||||
|
</description>
|
||||||
|
<arg name="reason_string" type="string" optional="true" summary="optional human-readable reason for placement failure"/>
|
||||||
|
</event>
|
||||||
|
|
||||||
|
</interface>
|
||||||
|
|
||||||
|
</protocol>
|
||||||
Loading…
Add table
Reference in a new issue