refactor(protocols): trim cutefish_shell_v1 to the desktop surface and drop window management
reionwong
2 weeks ago
parent
7abd92248c
commit
10af970ceb
@ -1,481 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<protocol name="cutefish_window_management_v1">
|
||||
|
||||
<description summary="task list and window control for cutefish-shell">
|
||||
Lets the trusted Cutefish shell enumerate and control the ordinary
|
||||
application windows the compositor manages, which is what the dock's task
|
||||
list, the status bar and the launcher are built on.
|
||||
|
||||
Only ordinary application windows are announced. The shell's own
|
||||
cutefish_shell_v1 surfaces - the desktop, the panels, the launcher and the
|
||||
notification banners - are never part of this list. Ordinary toplevels
|
||||
whose app_id is exactly cutefish-shell are also excluded.
|
||||
|
||||
Every request here is a trusted shell command. Unlike xdg-activation or
|
||||
xdg_toplevel.move they carry no input serial: the shell acts on behalf of
|
||||
the user through its own UI, not on behalf of the target application.
|
||||
|
||||
The compositor only advertises this global to the one trusted shell client
|
||||
it was handed by the session. Ordinary applications never see it.
|
||||
|
||||
Warning! Not a standard protocol. Backward-incompatible changes are made by
|
||||
bumping the interface version.
|
||||
</description>
|
||||
|
||||
<interface name="cutefish_window_management_v1" version="1">
|
||||
<description summary="the managed window list">
|
||||
On bind the compositor announces every application window that already
|
||||
exists, each one followed by its state and a done event, and then keeps
|
||||
sending changes. Rebinding after a shell restart therefore repopulates
|
||||
the whole task list.
|
||||
</description>
|
||||
|
||||
<enum name="picked_kind">
|
||||
<description summary="what is shown at a picked position"/>
|
||||
<entry name="none" value="0" summary="nothing that can be captured as a window"/>
|
||||
<entry name="window" value="1" summary="an announced application window"/>
|
||||
<entry name="desktop" value="2" summary="the shell's desktop"/>
|
||||
<entry name="panel" value="3" summary="a shell panel such as the status bar"/>
|
||||
<entry name="dock" value="4" summary="the shell's dock"/>
|
||||
</enum>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="stop managing windows">
|
||||
Existing cutefish_window_v1 objects stay valid until destroyed.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="quit_application">
|
||||
<description summary="the application menu's Quit">
|
||||
Asks every top-level window of the window's application to close, as
|
||||
xdg_toplevel.close does; dialogs are left alone, so a second Quit asks
|
||||
again rather than dismissing a prompt. An application is the task-list
|
||||
windows of one app_id, as the dock groups them, or of one process for
|
||||
windows without an app_id. Their processes that have no task-list
|
||||
window left a few seconds later are terminated through the session's
|
||||
application runtime; one that still shows a window, typically to ask
|
||||
about unsaved changes, is not.
|
||||
</description>
|
||||
<arg name="window" type="object" interface="cutefish_window_v1"/>
|
||||
</request>
|
||||
|
||||
<request name="hide_application">
|
||||
<description summary="the application menu's Hide">
|
||||
Hides every window of the window's application, as
|
||||
cutefish_window_v1.hide does.
|
||||
</description>
|
||||
<arg name="window" type="object" interface="cutefish_window_v1"/>
|
||||
</request>
|
||||
|
||||
<request name="hide_other_applications">
|
||||
<description summary="the application menu's Hide Others">
|
||||
Hides the windows of every application but the window's; with no
|
||||
window, of every application.
|
||||
</description>
|
||||
<arg name="window" type="object" interface="cutefish_window_v1" allow-null="true"/>
|
||||
</request>
|
||||
|
||||
<request name="pick">
|
||||
<description summary="find the window shown at a position">
|
||||
Asks which window is shown at a position in global logical
|
||||
coordinates, found the way the pointer finds it but looking through
|
||||
screen capture surfaces and their popups, so the capture interface
|
||||
can pick what is under it. Answered by picked with the same serial.
|
||||
</description>
|
||||
<arg name="serial" type="uint"/>
|
||||
<arg name="x" type="int"/>
|
||||
<arg name="y" type="int"/>
|
||||
</request>
|
||||
|
||||
<request name="activate_desk">
|
||||
<description summary="switch to a desk">
|
||||
Slides to the desk as clicking it does. Ignored for a desk that no
|
||||
longer exists and while desks are being switched.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
</request>
|
||||
|
||||
<request name="create_desk">
|
||||
<description summary="add a desk after the last one">
|
||||
Ignored when there are as many desks as the compositor allows. With
|
||||
`activate` 1 the new desk is also switched to.
|
||||
</description>
|
||||
<arg name="activate" type="uint"/>
|
||||
</request>
|
||||
|
||||
<request name="remove_desk">
|
||||
<description summary="remove a desk, keeping its windows">
|
||||
The desk's windows go to the desk on its left, or on its right when it
|
||||
is the first, below that desk's own windows. Removing the active desk
|
||||
slides to that desk first. Ignored for the only desk.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
</request>
|
||||
|
||||
<request name="set_desk_name">
|
||||
<description summary="name a desk">
|
||||
An empty name gives the desk its default name back.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
<arg name="name" type="string"/>
|
||||
</request>
|
||||
|
||||
<request name="create_surface_capture_source">
|
||||
<description summary="a capture source of the shell's own window as it is shown">
|
||||
Creates an ext_image_capture_source_v1 of the window one of the
|
||||
shell's own surfaces produced, with what the compositor draws around
|
||||
it: the glass, the outline, the shadow and the transparent margins
|
||||
the shadow needs, so a still picture of the dock looks the way the
|
||||
dock does on screen. The buffer covers the shadow bounds of what
|
||||
casts the shadow - the rounded body of the dock, not the transparent
|
||||
room of its surface around it - at the scale of the output that holds
|
||||
most of the window. A surface that has no window yet gives a source
|
||||
that cannot be captured. In every other way the source behaves like
|
||||
the one cutefish_window_v1.create_capture_source gives.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="ext_image_capture_source_v1"/>
|
||||
<arg name="surface" type="object" interface="wl_surface"/>
|
||||
</request>
|
||||
|
||||
<event name="window">
|
||||
<description summary="a window appeared">
|
||||
A new cutefish_window_v1 object for an application window. Its state
|
||||
follows immediately, terminated by cutefish_window_v1.done.
|
||||
|
||||
`id_hi` and `id_lo` are the high and low 32 bits of the compositor's
|
||||
stable 64-bit window identifier. Wayland has no 64-bit scalar, so the
|
||||
identifier is carried as two uints; it is unique for the lifetime of
|
||||
the compositor and is never reused.
|
||||
|
||||
The same window's ext_foreign_toplevel_handle_v1 identifier is
|
||||
"cutefish-" followed by this identifier in decimal, so a capture
|
||||
client can be told which window to capture.
|
||||
</description>
|
||||
<arg name="window" type="new_id" interface="cutefish_window_v1"/>
|
||||
<arg name="id_hi" type="uint"/>
|
||||
<arg name="id_lo" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="active_window">
|
||||
<description summary="the active window changed">
|
||||
The identifier of the active managed application, or zero when no
|
||||
application is active. An ordinary cutefish-shell toplevel taking
|
||||
keyboard focus preserves the previous managed application context.
|
||||
</description>
|
||||
<arg name="id_hi" type="uint"/>
|
||||
<arg name="id_lo" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="initial_state_done">
|
||||
<description summary="the initial enumeration is complete">
|
||||
Sent once, after the windows that existed at bind time have all been
|
||||
announced. A shell that is rebuilding its task list can hold off
|
||||
drawing until this arrives.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<event name="picked">
|
||||
<description summary="the window shown at a picked position">
|
||||
The answer to pick. For a window, id_hi and id_lo name it, and a
|
||||
popup is answered with the window it belongs to; otherwise they are
|
||||
zero.
|
||||
</description>
|
||||
<arg name="serial" type="uint"/>
|
||||
<arg name="kind" type="uint" enum="picked_kind"/>
|
||||
<arg name="id_hi" type="uint"/>
|
||||
<arg name="id_lo" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="desk">
|
||||
<description summary="a desk was added">
|
||||
Desks are announced in order, before initial_state_done for those that
|
||||
exist at bind time; a new desk is always the last. `desk` is its
|
||||
identifier, unique for the lifetime of the compositor and never
|
||||
reused, and never zero.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="desk_removed">
|
||||
<description summary="a desk was removed">
|
||||
Its windows have moved to another desk, which their desk events say.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="desk_name">
|
||||
<description summary="a desk's name">
|
||||
Empty while the desk has its default name, which the shell words
|
||||
itself from the desk's position, as "Desk 2".
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
<arg name="name" type="string"/>
|
||||
</event>
|
||||
|
||||
<event name="active_desk">
|
||||
<description summary="the desk in front of the user">
|
||||
There is always one.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="cutefish_window_v1" version="1">
|
||||
<description summary="one managed application window">
|
||||
State arrives as individual events followed by done. The shell should
|
||||
apply a batch only when done is received.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="invalid_geometry" value="0" summary="negative width or height"/>
|
||||
</enum>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="stop tracking this window"/>
|
||||
</request>
|
||||
|
||||
<request name="activate">
|
||||
<description summary="raise the window and give it the keyboard focus">
|
||||
Unhides the window first if it is hidden, and restores it if it is
|
||||
minimized.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="minimize"/>
|
||||
<request name="restore"/>
|
||||
|
||||
<request name="close">
|
||||
<description summary="ask the application to close the window">
|
||||
Sends the ordinary xdg_toplevel.close; the application decides what to
|
||||
do about it. A window that is not responsive gets not_responding
|
||||
instead.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="toggle_maximize"/>
|
||||
|
||||
<request name="start_move">
|
||||
<description summary="begin an interactive move of this window">
|
||||
Used by the status bar's window menu. No input serial is required.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="set_minimized_geometry">
|
||||
<description summary="where the window minimizes to">
|
||||
The rectangle, in the coordinate space of `panel`, that this window's
|
||||
task-list entry occupies. The compositor uses it as the target of the
|
||||
minimize animation. `panel` must be a surface belonging to the same
|
||||
client.
|
||||
|
||||
Passing a zero-sized rectangle clears the association.
|
||||
</description>
|
||||
<arg name="panel" type="object" interface="wl_surface"/>
|
||||
<arg name="x" type="int"/>
|
||||
<arg name="y" type="int"/>
|
||||
<arg name="width" type="int"/>
|
||||
<arg name="height" type="int"/>
|
||||
</request>
|
||||
|
||||
<request name="handoff">
|
||||
<description summary="the dock now shows the minimized window">
|
||||
Answers minimize_landed. Send it once the panel surface has committed
|
||||
a frame that shows the window's thumbnail at its minimized geometry;
|
||||
the compositor then stops drawing the window there. Ignored when no
|
||||
landing is pending.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="hide">
|
||||
<description summary="take the window off the screen without minimizing it">
|
||||
The window disappears at once: no animation, no thumbnail, and no
|
||||
task-list slot to land on. Its state is kept underneath, so a
|
||||
minimized window stays minimized and comes back to the dock when it
|
||||
is unhidden. A hidden window cannot be activated; if it held the
|
||||
keyboard focus, the focus moves on as it does for a closed window.
|
||||
|
||||
cutefish_window_management_v1.hide_application and
|
||||
hide_other_applications apply it to whole applications.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="unhide">
|
||||
<description summary="show a hidden window again">
|
||||
The window reappears in the state it was hidden in, in place and with
|
||||
no animation. It is neither raised nor activated; send activate for
|
||||
that. Ignored when the window is not hidden.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="move_to_desk">
|
||||
<description summary="send the window to a desk">
|
||||
Its dialogs go with it. Zero puts it on every desk. A window on the
|
||||
active desk slides off towards the desk it goes to, and does not take
|
||||
the user along.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
</request>
|
||||
|
||||
<request name="force_quit">
|
||||
<description summary="end the application behind the window">
|
||||
Ends the client process at once, without asking it: what the shell
|
||||
offers once not_responding was sent. When the session started the
|
||||
process in an application scope of its own, the rest of that scope
|
||||
ends with it. Anything the application did not save is lost.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="create_capture_source">
|
||||
<description summary="a capture source of the window as it is shown">
|
||||
Creates an ext_image_capture_source_v1 of the window with what the
|
||||
compositor draws around it: the outline, the shadow and the
|
||||
transparent margins the shadow needs, so a still picture of the
|
||||
window looks the way the window does on screen. The buffer covers
|
||||
the window's shadow bounds instead of its bounds, at the scale of
|
||||
the output that holds most of the window; a window that fills its
|
||||
area casts no shadow and gives the same picture as the toplevel
|
||||
source. In every other way the source behaves like one from
|
||||
ext_foreign_toplevel_image_capture_source_manager_v1.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="ext_image_capture_source_v1"/>
|
||||
</request>
|
||||
|
||||
<event name="title">
|
||||
<arg name="title" type="string"/>
|
||||
</event>
|
||||
|
||||
<event name="app_id">
|
||||
<arg name="app_id" type="string"/>
|
||||
</event>
|
||||
|
||||
<event name="pid">
|
||||
<description summary="the process that owns the window">
|
||||
Taken from the Wayland client credentials of the connection the
|
||||
window's xdg_surface was created on, or for an X11 window from the
|
||||
credentials the X server holds for its client connection. Never from
|
||||
a client-supplied property such as _NET_WM_PID. Zero when unknown.
|
||||
</description>
|
||||
<arg name="pid" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="state">
|
||||
<description summary="the window's boolean state">
|
||||
Each argument is 1 or 0. `hidden` is independent of the others: a
|
||||
window can be both hidden and minimized.
|
||||
</description>
|
||||
<arg name="active" type="uint"/>
|
||||
<arg name="minimized" type="uint"/>
|
||||
<arg name="maximized" type="uint"/>
|
||||
<arg name="fullscreen" type="uint"/>
|
||||
<arg name="hidden" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="geometry">
|
||||
<description summary="the outer window bounds in global coordinates"/>
|
||||
<arg name="x" type="int"/>
|
||||
<arg name="y" type="int"/>
|
||||
<arg name="width" type="int"/>
|
||||
<arg name="height" type="int"/>
|
||||
</event>
|
||||
|
||||
<event name="done">
|
||||
<description summary="the end of a batch of state changes">
|
||||
Everything sent since the previous done applies atomically.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<event name="closed">
|
||||
<description summary="the window is gone">
|
||||
No further events are sent. The shell should destroy the object.
|
||||
</description>
|
||||
</event>
|
||||
<event name="application_menu">
|
||||
<description summary="the window's DBusMenu endpoint">
|
||||
Service and object path of a com.canonical.dbusmenu on the session bus.
|
||||
Empty strings clear the endpoint. Applies with the next done event.
|
||||
</description>
|
||||
<arg name="service_name" type="string"/>
|
||||
<arg name="object_path" type="string"/>
|
||||
</event>
|
||||
|
||||
<event name="thumbnail">
|
||||
<description summary="how the window looked when it was minimized">
|
||||
Sent once the window is minimized: the last frame the compositor
|
||||
presented for it, outline and shadow excluded, for the shell
|
||||
to show in the window's place. Also sent during the initial
|
||||
enumeration for windows that are already minimized.
|
||||
|
||||
May be replaced while minimizing. Before minimize_landed, the final
|
||||
thumbnail contains the same raster the compositor holds at the slot.
|
||||
Upload it unchanged to preserve its edge pixels and sampling at handoff.
|
||||
|
||||
`fd` is a read-only shared memory file of width * height * 4 bytes,
|
||||
rows top to bottom, in the byte order of wl_shm format argb8888 with
|
||||
premultiplied alpha. The shell maps it, copies what it needs and
|
||||
closes it. No thumbnail is sent to clear one: the image stops applying
|
||||
once the state event reports the window as no longer minimized.
|
||||
Applies with the next done event.
|
||||
</description>
|
||||
<arg name="fd" type="fd"/>
|
||||
<arg name="width" type="uint"/>
|
||||
<arg name="height" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="minimize_landed">
|
||||
<description summary="the minimize animation reached the dock">
|
||||
The window has arrived at its minimized geometry, without shadow or
|
||||
outline, and the compositor keeps drawing it there until the shell
|
||||
sends handoff, or for at most 250 ms. Showing the thumbnail and then
|
||||
sending handoff replaces the window with no frame in between.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<event name="parent">
|
||||
<description summary="the window this one is transient for">
|
||||
The identifier of the xdg_toplevel parent, or zero when the window
|
||||
stands on its own. A dialog such as a save prompt has a parent; the
|
||||
shell leaves those alone when it asks an application to quit, since
|
||||
closing the prompt would answer it on the user's behalf. Applies with
|
||||
the next done event.
|
||||
</description>
|
||||
<arg name="id_hi" type="uint"/>
|
||||
<arg name="id_lo" type="uint"/>
|
||||
</event>
|
||||
<event name="skip_taskbar">
|
||||
<description summary="effective application presentation exclusion">
|
||||
When set, omit this window from the dock, status bar application
|
||||
identity and window switcher. It remains managed and may receive focus.
|
||||
Apply this state together with the other events at done.
|
||||
</description>
|
||||
<arg name="skip" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="desk">
|
||||
<description summary="the desk the window is on">
|
||||
Zero for a window on every desk: one the user put there, an always on
|
||||
top window or a system dialog. A window on a desk that is not active
|
||||
is not on screen, and activating it switches to its desk. Applies with
|
||||
the next done event.
|
||||
</description>
|
||||
<arg name="desk" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="responsive">
|
||||
<description summary="whether the application answers the compositor">
|
||||
Zero once the client stopped answering the compositor's pings past a
|
||||
timeout, one when it answers again. The compositor dims the window
|
||||
meanwhile. Every window starts out responsive. Applies with the next
|
||||
done event.
|
||||
</description>
|
||||
<arg name="responsive" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="not_responding">
|
||||
<description summary="the user is waiting on a window that stopped answering">
|
||||
Sent when the user presses on, types into or closes the window while
|
||||
it is not responsive. The shell is expected to offer force_quit. With
|
||||
no shell bound to offer it, closing such a window ends the
|
||||
application instead.
|
||||
</description>
|
||||
</event>
|
||||
</interface>
|
||||
</protocol>
|
||||
Loading…
Reference in New Issue