119 lines
5.4 KiB
XML
119 lines
5.4 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<protocol name="wmaker_popup_v1">
|
|
<copyright>
|
|
Copyright © 2026 Window Maker Team
|
|
|
|
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>
|
|
|
|
<description summary="Window Maker popup positioning protocol">
|
|
This protocol allows Window Maker WINGs clients (such as WPrefs) to
|
|
request specific screen positions for borderless popup-style toplevel
|
|
windows (menu editor items, popup dropdown menus, tear-off menus).
|
|
|
|
Standard xdg_shell does not allow clients to position toplevels — only
|
|
the compositor decides placement. This is correct for normal application
|
|
windows but breaks WINGs UI patterns that require client-driven positioning
|
|
(e.g., a dropdown menu must appear directly below its triggering button).
|
|
|
|
A client wraps an xdg_toplevel with a wmaker_popup object and calls
|
|
set_position(x, y) before the surface is mapped. The compositor honours
|
|
the position when the surface becomes visible. Subsequent set_position
|
|
calls reposition the surface immediately.
|
|
|
|
The popup loses no other xdg_toplevel features — it remains an ordinary
|
|
toplevel for input, focus, and lifetime purposes. The compositor is
|
|
additionally expected to omit decorations and skip taskbar/dock listing
|
|
for popup-wrapped toplevels (typically signalled via app_id).
|
|
</description>
|
|
|
|
<interface name="wmaker_popup_manager_v1" version="1">
|
|
<description summary="manager for wmaker_popup objects">
|
|
Singleton global advertised by Window Maker compositors that support
|
|
client-driven popup positioning. Clients bind once and use it to wrap
|
|
xdg_toplevel objects.
|
|
</description>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="release the manager">
|
|
Destroy the manager. Existing wmaker_popup objects remain valid.
|
|
</description>
|
|
</request>
|
|
|
|
<request name="get_popup">
|
|
<description summary="wrap an xdg_toplevel as a popup">
|
|
Wrap the given xdg_toplevel in a wmaker_popup object so the client
|
|
can drive its position. The toplevel must not yet be mapped.
|
|
Calling get_popup more than once for the same toplevel is a
|
|
protocol error.
|
|
</description>
|
|
<arg name="id" type="new_id" interface="wmaker_popup_v1"
|
|
summary="the new popup object"/>
|
|
<arg name="toplevel" type="object" interface="xdg_toplevel"
|
|
summary="the toplevel to wrap"/>
|
|
</request>
|
|
</interface>
|
|
|
|
<interface name="wmaker_popup_v1" version="1">
|
|
<description summary="client-positioned popup toplevel">
|
|
Wrapper around an xdg_toplevel that lets the client drive screen
|
|
placement. Position is in coordinates relative to the parent
|
|
toplevel's top-left corner, or compositor-global if no parent is
|
|
set. The parent is set via set_parent() and is typically the
|
|
application's main toplevel (e.g., the WPrefs main window).
|
|
</description>
|
|
|
|
<enum name="error">
|
|
<entry name="invalid_position" value="0"
|
|
summary="position is outside any output"/>
|
|
</enum>
|
|
|
|
<request name="destroy" type="destructor">
|
|
<description summary="release the popup">
|
|
Destroying the popup reverts the toplevel to compositor-driven
|
|
placement. The underlying xdg_toplevel remains valid until the
|
|
client destroys it explicitly.
|
|
</description>
|
|
</request>
|
|
|
|
<request name="set_parent">
|
|
<description summary="set the parent toplevel for relative positioning">
|
|
Subsequent set_position calls are interpreted as offsets from
|
|
the parent toplevel's top-left corner. Pass NULL to revert to
|
|
compositor-global coordinates.
|
|
</description>
|
|
<arg name="parent" type="object" interface="xdg_toplevel"
|
|
allow-null="true" summary="parent toplevel or null"/>
|
|
</request>
|
|
|
|
<request name="set_position">
|
|
<description summary="set the position of the popup">
|
|
Place the popup at (x, y). If a parent has been set via
|
|
set_parent, coordinates are relative to the parent's top-left
|
|
corner. Otherwise, coordinates are compositor-global.
|
|
Takes effect on the next surface commit if the toplevel is not
|
|
yet mapped, or immediately if already mapped.
|
|
</description>
|
|
<arg name="x" type="int" summary="x offset"/>
|
|
<arg name="y" type="int" summary="y offset"/>
|
|
</request>
|
|
</interface>
|
|
</protocol>
|