diff options
Diffstat (limited to 'protocol')
| -rw-r--r-- | protocol/river-layout-v2.xml | 256 | ||||
| -rw-r--r-- | protocol/river-layout-v3.xml | 181 |
2 files changed, 181 insertions, 256 deletions
diff --git a/protocol/river-layout-v2.xml b/protocol/river-layout-v2.xml deleted file mode 100644 index f0c82e0..0000000 --- a/protocol/river-layout-v2.xml +++ /dev/null @@ -1,256 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<protocol name="river_layout_v2"> - <copyright> - Copyright 2020-2021 The River Developers - - Permission to use, copy, modify, and/or distribute this software for any - purpose with or without fee is hereby granted, provided that the above - copyright notice and this permission notice appear in all copies. - - THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR - ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF - OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - </copyright> - - <description summary="let clients propose view positions and dimensions"> - This protocol specifies a way for clients to propose arbitrary positions and - dimensions for a set of views on a specific output of a compositor through - the river_layout_v2 object. - - This set of views is logically structured as a simple list. Views - in this list cannot be individually addressed, instead the order of - requests/events is significant. - - The entire set of proposed positions and dimensions for the views in the - list are called a layout. Due to their list heritage, layouts are also - logically strictly linear; Any complex underlying data structure a client - may use when generating the layout is lost in transmission. This is an - intentional limitation. - - Note that the client may need to handle multiple layout demands per - river_layout_v2 object simultaneously. - - Warning! The protocol described in this file is currently in the testing - phase. Backward compatible changes may be added together with the - corresponding interface version bump. Backward incompatible changes can - only be done by creating a new major version of the extension. - </description> - - <interface name="river_layout_manager_v2" version="1"> - <description summary="manage river layout objects"> - A global factory for river_layout_v2 objects. - </description> - - <request name="destroy" type="destructor"> - <description summary="destroy the river_layout_manager object"> - This request indicates that the client will not use the - river_layout_manager object any more. Objects that have been created - through this instance are not affected. - </description> - </request> - - <request name="get_layout"> - <description summary="create a river_layout_v2 object"> - This creates a new river_layout_v2 object for the given wl_output. - - All layout related communication is done through this interface. - - The namespace is used by the compositor to decide which river_layout_v2 - object will receive layout demands for the output. - - The namespace is required to be be unique per-output. Furthermore, - two separate clients may not share a namespace on separate outputs. If - these conditions are not upheld, the the namespace_in_use event will - be sent directly after creation of the river_layout_v2 object. - </description> - <arg name="id" type="new_id" interface="river_layout_v2"/> - <arg name="output" type="object" interface="wl_output"/> - <arg name="namespace" type="string" summary="namespace of the layout object"/> - </request> - </interface> - - <interface name="river_layout_v2" version="1"> - <description summary="receive and respond to layout demands"> - This interface allows clients to receive layout demands from the - compositor for a specific output and subsequently propose positions and - dimensions of individual views. - </description> - - <enum name="error"> - <entry name="count_mismatch" value="0" summary="number of - proposed dimensions does not match number of views in layout"/> - <entry name="already_committed" value="1" summary="the layout demand with - the provided serial was already committed"/> - </enum> - - <request name="destroy" type="destructor"> - <description summary="destroy the river_layout_v2 object"> - This request indicates that the client will not use the river_layout_v2 - object any more. - </description> - </request> - - <event name="namespace_in_use"> - <description summary="the requested namespace is already in use"> - After this event is sent, all requests aside from the destroy event - will be ignored by the server. If the client wishes to try again with - a different namespace they must create a new river_layout_v2 object. - </description> - </event> - - <event name="layout_demand"> - <description summary="the compositor requires a layout"> - The compositor sends this event to inform the client that it requires a - layout for a set of views. - - The usable width and height height indicate the space in which the - client can safely position views without interfering with desktop - widgets such as panels. - - The serial of this event is used to identify subsequent events and - request as belonging to this layout demand. Beware that the client - might need to handle multiple layout demands at the same time. - - The server will ignore responses to all but the most recent - layout demand. Thus, clients are only required to respond to the most - recent layout_demand received. If a newer layout_demand is received - before the client has finished responding to an old demand, the client - may abort work on the old demand as any further work would be wasted. - </description> - <arg name="view_count" type="uint" summary="number of views in the layout"/> - <arg name="usable_width" type="uint" summary="width of the usable area"/> - <arg name="usable_height" type="uint" summary="height of the usable area"/> - <arg name="tags" type="uint" summary="tags of the output, 32-bit bitfield"/> - <arg name="serial" type="uint" summary="serial of the layout demand"/> - </event> - - <event name="advertise_view"> - <description summary="make layout client aware of view"> - This event is sent by the server as part of the layout demand with - matching serial. It provides additional information about one of - the views to be arranged. - - Every view part of the layout demand is advertised exactly once, - in the order of the view list. - </description> - <arg name="tags" type="uint" summary="tags of the view, 32-bit bitfield"/> - <arg name="app_id" type="string" summary="view app-id" allow-null="true"/> - <arg name="serial" type="uint" summary="serial of the layout demand"/> - </event> - - <event name="advertise_done"> - <description summary="all views have been advertised"> - This event is sent by the server as the last event of the layout - demand with matching serial, after all advertise_view events. - </description> - <arg name="serial" type="uint" summary="serial of the layout demand"/> - </event> - - <request name="push_view_dimensions"> - <description summary="propose dimensions of the next view"> - This request proposes a size and position of a view in the layout demand - with matching serial. - - Pushed view dimensions apply to the views in the same order they were - advertised. That is, the first push_view_dimensions request applies - to the first view advertised, the second to the second, and so on. - - A client must propose position and dimensions for the entire set of - views. Proposing too many or too few view dimensions is a protocol error. - - This request may be sent before the corresponding view has been - advertised. - - The x and y coordinates are relative to the usable area of the output, - with (0,0) as the top left corner. - </description> - <arg name="serial" type="uint" summary="serial of layout demand"/> - <arg name="x" type="int" summary="x coordinate of view"/> - <arg name="y" type="int" summary="y coordinate of view"/> - <arg name="width" type="uint" summary="width of view"/> - <arg name="height" type="uint" summary="height of view"/> - </request> - - <request name="commit"> - <description summary="commit a layout"> - This request indicates that the client is done pushing dimensions - and the compositor may apply the layout. This completes the layout - demand with matching serial, any other requests sent with the serial - are a protocol error. - - The compositor is free to use this proposed layout however it chooses, - including ignoring it. - </description> - <arg name="serial" type="uint" summary="serial of layout demand"/> - </request> - - <event name="set_int_value"> - <description summary="an int value has been set"> - This event indicates that the value of this river_layout_v2 object - with the given name has been set to the given value. - - This event will be followed by a layout_demand if necessary (i.e. if - this layout object is currently being used by the compositor to - layout an output) - </description> - <arg name="name" type="string"/> - <arg name="value" type="int"/> - </event> - - <event name="mod_int_value"> - <description summary="an int value has been modified"> - This event indicates that the value of this river_layout_v2 object - with the given name has been modifed by the given delta. - - This event will be followed by a layout_demand if necessary (i.e. if - this layout object is currently being used by the compositor to - layout an output) - </description> - <arg name="name" type="string"/> - <arg name="delta" type="int"/> - </event> - - <event name="set_fixed_value"> - <description summary="a fixed value has been set"> - This event indicates that the value of this river_layout_v2 object - with the given name has been set to the given value. - - This event will be followed by a layout_demand if necessary (i.e. if - this layout object is currently being used by the compositor to - layout an output) - </description> - <arg name="name" type="string"/> - <arg name="value" type="fixed"/> - </event> - - <event name="mod_fixed_value"> - <description summary="a fixed value has been modified"> - This event indicates that the value of this river_layout_v2 object - with the given name has been modifed by the given delta. - - This event will be followed by a layout_demand if necessary (i.e. if - this layout object is currently being used by the compositor to - layout an output) - </description> - <arg name="name" type="string"/> - <arg name="delta" type="fixed"/> - </event> - - <event name="set_string_value"> - <description summary="a string value has been set"> - This event indicates that the value of this river_layout_v2 object - with the given name has been set to the given value. - - This event will be followed by a layout_demand if necessary (i.e. if - this layout object is currently being used by the compositor to - layout an output) - </description> - <arg name="name" type="string"/> - <arg name="value" type="string"/> - </event> - </interface> -</protocol> diff --git a/protocol/river-layout-v3.xml b/protocol/river-layout-v3.xml new file mode 100644 index 0000000..3363355 --- /dev/null +++ b/protocol/river-layout-v3.xml @@ -0,0 +1,181 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="river_layout_v3"> + <copyright> + Copyright 2020-2021 The River Developers + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </copyright> + + <description summary="let clients propose view positions and dimensions"> + This protocol specifies a way for clients to propose arbitrary positions + and dimensions for a set of views on a specific output of a compositor + through the river_layout_v3 object. + + Layouts are a strictly linear list of views, the position and dimensions + of which are supplied by the client. Any complex underlying data structure + a client may use when generating the layout is lost in transmission. This + is an intentional limitation. + + Additonally, this protocol allows the compositor to deliver arbitrary + user-provided commands associated with a layout to clients. A client + may use these commands to implement runtime configuration/control, or + may ignore them entirely. How the user provides these commands to the + compositor is not specified by this protocol and left to compositor policy. + + Warning! The protocol described in this file is currently in the + testing phase. Backward compatible changes may be added together with + the corresponding interface version bump. Backward incompatible changes + can only be done by creating a new major version of the extension. + </description> + + <interface name="river_layout_manager_v3" version="1"> + <description summary="manage river layout objects"> + A global factory for river_layout_v3 objects. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the river_layout_manager object"> + This request indicates that the client will not use the + river_layout_manager object any more. Objects that have been created + through this instance are not affected. + </description> + </request> + + <request name="get_layout"> + <description summary="create a river_layout_v3 object"> + This creates a new river_layout_v3 object for the given wl_output. + + All layout related communication is done through this interface. + + The namespace is used by the compositor to decide which river_layout_v3 + object will receive layout demands for the output. + + The namespace is required to be be unique per-output. Furthermore, + two separate clients may not share a namespace on separate outputs. If + these conditions are not upheld, the the namespace_in_use event will + be sent directly after creation of the river_layout_v3 object. + </description> + <arg name="id" type="new_id" interface="river_layout_v3"/> + <arg name="output" type="object" interface="wl_output"/> + <arg name="namespace" type="string" summary="namespace of the layout object"/> + </request> + </interface> + + <interface name="river_layout_v3" version="1"> + <description summary="receive and respond to layout demands"> + This interface allows clients to receive layout demands from the + compositor for a specific output and subsequently propose positions and + dimensions of individual views. + </description> + + <enum name="error"> + <entry name="count_mismatch" value="0" summary="number of + proposed dimensions does not match number of views in layout"/> + <entry name="already_committed" value="1" summary="the layout demand with + the provided serial was already committed"/> + </enum> + + <request name="destroy" type="destructor"> + <description summary="destroy the river_layout_v3 object"> + This request indicates that the client will not use the river_layout_v3 + object any more. + </description> + </request> + + <event name="namespace_in_use"> + <description summary="the requested namespace is already in use"> + After this event is sent, all requests aside from the destroy event + will be ignored by the server. If the client wishes to try again with + a different namespace they must create a new river_layout_v3 object. + </description> + </event> + + <event name="layout_demand"> + <description summary="the compositor requires a layout"> + The compositor sends this event to inform the client that it requires a + layout for a set of views. + + The usable width and height height indicate the space in which the + client can safely position views without interfering with desktop + widgets such as panels. + + The serial of this event is used to identify subsequent requests as + belonging to this layout demand. Beware that the client might need + to handle multiple layout demands at the same time. + + The server will ignore responses to all but the most recent layout + demand. Thus, clients are only required to respond to the most recent + layout_demand received. If a newer layout_demand is received before + the client has finished responding to an old demand, the client should + abort work on the old demand as any further work would be wasted. + </description> + <arg name="view_count" type="uint" summary="number of views in the layout"/> + <arg name="usable_width" type="uint" summary="width of the usable area"/> + <arg name="usable_height" type="uint" summary="height of the usable area"/> + <arg name="tags" type="uint" summary="tags of the output, 32-bit bitfield"/> + <arg name="serial" type="uint" summary="serial of the layout demand"/> + </event> + + <request name="push_view_dimensions"> + <description summary="propose dimensions of the next view"> + This request proposes a size and position for a view in the layout demand + with matching serial. + + A client must send this request for every view that is part of the + layout demand. The number of views in the layout is given by the + view_count argument of the layout_demand event. Pushing too many or + too few view dimensions is a protocol error. + + The x and y coordinates are relative to the usable area of the output, + with (0,0) as the top left corner. + </description> + <arg name="x" type="int" summary="x coordinate of view"/> + <arg name="y" type="int" summary="y coordinate of view"/> + <arg name="width" type="uint" summary="width of view"/> + <arg name="height" type="uint" summary="height of view"/> + <arg name="serial" type="uint" summary="serial of layout demand"/> + </request> + + <request name="commit"> + <description summary="commit a layout"> + This request indicates that the client is done pushing dimensions + and the compositor may apply the layout. This completes the layout + demand with matching serial, any other requests sent with the serial + are a protocol error. + + The layout_name argument is a user-facing name or short description + of the layout that is being committed. The compositor may for example + display this on a status bar, though what exactly is done with it is + left to the compositor's discretion. + + The compositor is free to use this proposed layout however it chooses, + including ignoring it. + </description> + <arg name="layout_name" type="string" summary="name of committed layout"/> + <arg name="serial" type="uint" summary="serial of layout demand"/> + </request> + + <event name="user_command"> + <description summary="an argument of a user command"> + This event informs the client of a command sent to it by the user. + + The semantic meaning of the command is left for the client to + decide. It is also free to ignore it entirely if it so chooses. + + A layout_demand will be sent after this event if the compositor is + currently using this layout object to arrange the output. + </description> + <arg name="command" type="string"/> + </event> + </interface> +</protocol> |