unstable/remote-shell/remote-shell-unstable-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="remote_shell_unstable_v1">

  <copyright>
    Copyright 2016 The Chromium 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>

  <description summary="Create remote desktop-style surfaces">
    remote_shell allows clients to turn a wl_surface into a "real window"
    which can be stacked and activated by the user.

    Warning! The protocol described in this file is experimental and backward
    incompatible changes may be made. Backward compatible changes may be added
    together with the corresponding interface version bump. Backward
    incompatible changes are done by bumping the version number in the protocol
    and interface names and resetting the interface version. Once the protocol
    is to be declared stable, the 'z' prefix and the version number in the
    protocol and interface names are removed and the interface version number is
    reset.
  </description>

  <interface name="zcr_remote_shell_v1" version="20">
    <description summary="remote_shell">
      The global interface that allows clients to turn a wl_surface into a
      "real window" which is remotely managed but can be stacked, activated
      and made fullscreen by the user.
    </description>

    <enum name="container">
      <description summary="containers for remote surfaces">
	Determine how a remote surface should be stacked relative to other
	shell surfaces.
      </description>
      <entry name="default" value="1" summary="default container"/>
      <entry name="overlay" value="2" summary="system modal container"/>
    </enum>

    <enum name="state_type">
      <description summary="state types for remote surfaces">
	Defines common show states for shell surfaces.
      </description>
      <entry name="normal" value="1" summary="normal window state"/>
      <entry name="minimized" value="2" summary="minimized window state"/>
      <entry name="maximized" value="3" summary="maximized window state"/>
      <entry name="fullscreen" value="4" summary="fullscreen window state"/>
      <entry name="pinned" value="5" summary="pinned window state"/>
      <entry name="trusted_pinned" value="6" summary="trusted pinned window state"/>
      <entry name="moving" value="7" summary="moving window state"/>
      <entry name="resizing" value="8" summary="resizing window state"/>
      <entry name="left_snapped" value="9" summary="left snapped window state"/>
      <entry name="right_snapped" value="10" summary="right snapped window state"/>
      <entry name="pip" value="11" summary="pip window state"/>
    </enum>

    <enum name="error">
      <entry name="role" value="0" summary="given wl_surface has another role"/>
      <entry name="invalid_notification_key" value="1"
	     summary="invalid notification key"/>
    </enum>

    <enum name="layout_mode">
      <description summary="the layout mode">
	Determine how a client should layout surfaces.
      </description>
      <entry name="windowed" value="1" summary="multiple windows"/>
      <entry name="tablet" value="2" summary="restricted mode for tablet"/>
    </enum>

    <request name="destroy" type="destructor">
      <description summary="destroy remote_shell">
	Destroy this remote_shell object.

	Destroying a bound remote_shell object while there are surfaces
	still alive created by this remote_shell object instance is illegal
	and will result in a protocol error.
      </description>
    </request>

    <request name="get_remote_surface">
      <description summary="create a remote shell surface from a surface">
	This creates an remote_surface for the given surface and gives it the
	remote_surface role. A wl_surface can only be given a remote_surface
	role once. If get_remote_surface is called with a wl_surface that
	already has an active remote_surface associated with it, or if it had
	any other role, an error is raised.

	See the documentation of remote_surface for more details about what an
	remote_surface is and how it is used.
      </description>
      <arg name="id" type="new_id" interface="zcr_remote_surface_v1"/>
      <arg name="surface" type="object" interface="wl_surface"/>
      <arg name="container" type="uint"/>
    </request>

    <event name="activated">
      <description summary="activated surface changed">
	Notifies client that the activated surface changed.
      </description>
      <arg name="gained_active" type="object" interface="wl_surface" allow-null="true"/>
      <arg name="lost_active" type="object" interface="wl_surface" allow-null="true"/>
    </event>

    <request name="get_notification_surface">
      <description summary="create a notification surface from a surface">
	Creates a notification_surface for the given surface, gives it the
	notification_surface role and associated it with a notification id.
      </description>
      <arg name="id" type="new_id" interface="zcr_notification_surface_v1"/>
      <arg name="surface" type="object" interface="wl_surface"/>
      <arg name="notification_key" type="string" />
    </request>

    <event name="configuration_changed">
      <description summary="suggests a re-configuration of remote shell">
	[Deprecated] Suggests a re-configuration of remote shell.
      </description>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
      <arg name="transform" type="int"/>
      <arg name="scale_factor" type="fixed"/>
      <arg name="work_area_inset_left" type="int"/>
      <arg name="work_area_inset_top" type="int"/>
      <arg name="work_area_inset_right" type="int"/>
      <arg name="work_area_inset_bottom" type="int"/>
      <arg name="layout_mode" type="uint"/>
    </event>

    <!-- Version 5 additions -->

    <event name="workspace" since="5">
      <description summary="area of remote shell">
	[Deprecated] Defines an area of the remote shell used for layout. Each series of
	"workspace" events must be terminated by a "configure" event.
      </description>
      <arg name="display_id_hi" type="uint"/>
      <arg name="display_id_lo" type="uint"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
      <arg name="inset_left" type="int"/>
      <arg name="inset_top" type="int"/>
      <arg name="inset_right" type="int"/>
      <arg name="inset_bottom" type="int"/>
      <arg name="transform" type="int"/>
      <arg name="scale_factor" type="fixed"/>
      <arg name="is_internal" type="uint" summary="1 if screen is built-in"/>
    </event>

    <event name="configure" since="5">
      <description summary="suggests configuration of remote shell">
	Suggests a new configuration of the remote shell. Preceded by a series
	of "workspace" events.
      </description>
      <arg name="layout_mode" type="uint"/>
    </event>

    <!-- Version 8 additions -->

    <event name="default_device_scale_factor" since="8">
      <description summary="initialize scale configuration">
	Sends the default device scale factor.
      </description>
      <arg name="scale" type="int" summary="DP to pixels ratio, in 8.24 fixed point format"/>
    </event>

    <!-- Version 17 additions -->

    <request name="get_input_method_surface" since="17">
      <description summary="Create a input method surface from a surface">
	Creates an input_method_surface for the given surface, gives it
	the input_method_surface role.
      </description>
      <arg name="id" type="new_id" interface="zcr_input_method_surface_v1"/>
      <arg name="surface" type="object" interface="wl_surface"/>
    </request>

    <!-- Version 19 additions -->

    <event name="display_info" since="19">
      <description summary="extra display information">
	[Deprecated] Sends display size in pixels and display identification data, typically
	in EDID format. Followed by a "workspace_info" event for the same display.
      </description>
      <arg name="display_id_hi" type="uint"/>
      <arg name="display_id_lo" type="uint"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
      <arg name="identification_data" type="array"/>
    </event>

    <!-- Version 20 additions -->

    <event name="workspace_info" since="20">
      <description summary="area of remote shell in pixels">
	Sends display information such as size, work area and its related information.
	Each series of "workspace_info" events must be terminated by a "configure" event.
      </description>
      <arg name="display_id_hi" type="uint"/>
      <arg name="display_id_lo" type="uint"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
      <arg name="inset_left" type="int"/>
      <arg name="inset_top" type="int"/>
      <arg name="inset_right" type="int"/>
      <arg name="inset_bottom" type="int"/>
      <arg name="stable_inset_left" type="int"/>
      <arg name="stable_inset_top" type="int"/>
      <arg name="stable_inset_right" type="int"/>
      <arg name="stable_inset_bottom" type="int"/>
      <arg name="systemui_visibility" type="int" summary="systemui_visibility_state"/>
      <arg name="transform" type="int"/>
      <arg name="is_internal" type="uint" summary="1 if screen is built-in"/>
      <arg name="identification_data" type="array" summary="EDID blob data"/>
    </event>

  </interface>

  <interface name="zcr_remote_surface_v1" version="20">
    <description summary="A desktop window">
      An interface that may be implemented by a wl_surface, for
      implementations that provide a desktop-style user interface
      and allows for remotely managed windows.

      It provides requests to treat surfaces like windows, allowing to set
      properties like app id and geometry.

      The client must call wl_surface.commit on the corresponding wl_surface
      for the remote_surface state to take effect.

      For a surface to be mapped by the compositor the client must have
      committed both an remote_surface state and a buffer.
    </description>

    <enum name="systemui_visibility_state">
      <description summary="systemui visibility behavior">
	Determine the visibility behavior of the system UI.
      </description>
      <entry name="visible" value="1" summary="system ui is visible"/>
      <entry name="autohide_non_sticky" value="2" summary="system ui autohides and is not sticky"/>
      <entry name="autohide_sticky" value="3" summary="system ui autohides and is sticky"/>
    </enum>

    <enum name="orientation">
      <description summary="window orientation">
	The orientation of the window.
      </description>
      <entry name="portrait" value="1" summary="portrait"/>
      <entry name="landscape" value="2" summary="landscape"/>
    </enum>

    <enum name="window_type">
      <description summary="window type">
	The type of the window.
      </description>
      <entry name="normal" value="1" summary="normal app window"/>
      <entry name="system_ui" value="2" summary="window is treated as systemui"/>
    </enum>

    <request name="destroy" type="destructor">
      <description summary="Destroy the remote_surface">
	Unmap and destroy the window. The window will be effectively
	hidden from the user's point of view, and all state will be lost.
      </description>
    </request>

    <request name="set_app_id">
      <description summary="set application ID">
	Set an application identifier for the surface.
      </description>
      <arg name="app_id" type="string"/>
    </request>

    <request name="set_window_geometry">
      <description summary="set the new window geometry">
	[Deprecated] The window geometry of a window is its "visible bounds"
	from the user's perspective. Client-side decorations often have
	invisible portions like drop-shadows which should be ignored for the
	purposes of aligning, placing and constraining windows.

	The window geometry is double buffered, and will be applied at the
	time wl_surface.commit of the corresponding wl_surface is called.

	Once the window geometry of the surface is set once, it is not
	possible to unset it, and it will remain the same until
	set_window_geometry is called again, even if a new subsurface or
	buffer is attached.

	If never set, the value is the full bounds of the output. This
	updates dynamically on every commit.

	The arguments are given in the output coordinate space.

	The width and height must be greater than zero.
      </description>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <request name="set_scale">
      <description summary="set scale">
	Set a scale factor that will be applied to surface and all descendants.
      </description>
      <arg name="scale" type="fixed"/>
    </request>

    <request name="set_rectangular_shadow">
      <description summary="set a rectangular shadow">
	[Deprecated] Request that surface needs a rectangular shadow.

	This is only a request that the surface should have a rectangular
	shadow. The compositor may choose to ignore this request.

	The arguments are given in the output coordinate space and specifies
	the inner bounds of the shadow.

	The arguments are given in the output coordinate space.
	Specifying zero width and height will disable the shadow.
      </description>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <request name="set_rectangular_shadow_background_opacity">
      <description summary="suggests the window's background opacity">
	[Deprecated] Suggests the window's background opacity when the shadow is requested.
      </description>
      <arg name="opacity" type="fixed"/>
    </request>

    <request name="set_title">
      <description summary="set surface title">
	Set a short title for the surface.

	This string may be used to identify the surface in a task bar,
	window list, or other user interface elements provided by the
	compositor.

	The string must be encoded in UTF-8.
      </description>
      <arg name="title" type="string"/>
    </request>

    <request name="set_top_inset">
      <description summary="set top inset for surface">
	Set distance from the top of the surface to the contents.

	This distance typically represents the size of the window caption.
      </description>
      <arg name="height" type="int"/>
    </request>

    <request name="activate">
      <description summary="make the surface active">
	Make the surface active and bring it to the front.
      </description>
      <arg name="serial" type="uint" summary="the serial of the user event"/>
    </request>

    <request name="maximize">
      <description summary="maximize">
	Request that surface is maximized. The window geometry will be updated
	to whatever the compositor finds appropriate for a maximized window.

	This is only a request that the window should be maximized. The
	compositor may choose to ignore this request. The client should
	listen to set_maximized events to determine if the window was
	maximized or not.
      </description>
    </request>

    <request name="minimize">
      <description summary="minimize">
	Request that surface is minimized.

	This is only a request that the window should be minimized. The
	compositor may choose to ignore this request. The client should
	listen to set_minimized events to determine if the window was
	minimized or not.
      </description>
    </request>

    <request name="restore">
      <description summary="restore">
	Request that surface is restored. This restores the window geometry
	to what it was before the window was minimized, maximized or made
	fullscreen.

	This is only a request that the window should be restored. The
	compositor may choose to ignore this request. The client should
	listen to unset_maximized, unset_minimize and unset_fullscreen
	events to determine if the window was restored or not.
      </description>
    </request>

    <request name="fullscreen">
      <description summary="fullscreen">
	Request that surface is made fullscreen.

	This is only a request that the window should be made fullscreen.
	The compositor may choose to ignore this request. The client should
	listen to set_fullscreen events to determine if the window was
	made fullscreen or not.
      </description>
    </request>

    <request name="unfullscreen">
      <description summary="unfullscreen">
	Request that surface is made unfullscreen.

	This is only a request that the window should be made unfullscreen.
	The compositor may choose to ignore this request. The client should
	listen to unset_fullscreen events to determine if the window was
	made unfullscreen or not.
      </description>
    </request>

    <request name="pin">
      <description summary="pin">
	Request that surface is pinned.

	This is only a request that the window should be pinned.
	The compositor may choose to ignore this request. The client should
	listen to state_changed events to determine if the window was
	pinned or not. If trusted flag is non-zero, the app can prevent users
	from exiting the pinned mode.
      </description>
      <arg name="trusted" type="int"/>
    </request>

    <request name="unpin">
      <description summary="unpin">
	Request that surface is unpinned.

	This is only a request that the window should be unpinned.
	The compositor may choose to ignore this request. The client should
	listen to unset_pinned events to determine if the window was
	unpinned or not.
      </description>
    </request>

    <request name="set_system_modal">
      <description summary="suggests a re-layout of remote shell input area">
	Suggests a surface should become system modal.
      </description>
    </request>

    <request name="unset_system_modal">
      <description summary="suggests a re-layout of remote shell input area">
	Suggests a surface should become non system modal.
      </description>
    </request>

    <event name="close">
      <description summary="surface wants to be closed">
	The close event is sent by the compositor when the user
	wants the surface to be closed. This should be equivalent to
	the user clicking the close button in client-side decorations,
	if your application has any...

	This is only a request that the user intends to close your
	window. The client may choose to ignore this request, or show
	a dialog to ask the user to save their data...
      </description>
    </event>

    <event name="state_type_changed">
      <description summary="surface state type changed">
	[Deprecated] The state_type_changed event is sent by the compositor when
	the surface state changed.

	This is an event to notify that the window state changed in compositor.
	The state change may be triggered by a client's request, or some user
	action directly handled by the compositor. The client may choose to
	ignore this event.
      </description>
      <arg name="state_type" type="uint"/>
    </event>

    <!-- Version 2 additions -->

    <request name="set_rectangular_surface_shadow" since="2">
      <description summary="set a rectangular shadow">
	Request that surface needs a rectangular shadow.

	This is only a request that the surface should have a rectangular
	shadow. The compositor may choose to ignore this request.

	The arguments are given in the remote surface coordinate space and
	specifies inner bounds of the shadow. Specifying zero width and height
	will disable the shadow.
      </description>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <!-- Version 3 additions -->

    <request name="set_systemui_visibility" since="3">
      <description summary="requests the system ui visibility behavior for the surface">
	Requests how the surface will change the visibility of the system UI when it is made active.
      </description>
      <arg name="visibility" type="uint"/>
    </request>

    <!-- Version 4 additions -->

    <request name="set_always_on_top" since="4">
      <description summary="set always on top">
	Request that surface is made to be always on top.

	This is only a request that the window should be always on top.
	The compositor may choose to ignore this request.

      </description>
    </request>

    <request name="unset_always_on_top" since="4">
      <description summary="unset always on top">
	Request that surface is made to be not always on top.

	This is only a request that the window should be not always on top.
	The compositor may choose to ignore this request.
      </description>
    </request>

    <!-- Version 5 additions -->

    <event name="configure" since="5">
      <description summary="suggest a surface change">
	The configure event asks the client to change surface state.

	The client must apply the origin offset to window positions in
	set_window_geometry requests.

	The states listed in the event are state_type values, and might change
	due to a client request or an event directly handled by the compositor.

	Clients should arrange their surface for the new state, and then send an
	ack_configure request with the serial sent in this configure event at
	some point before committing the new surface.

	If the client receives multiple configure events before it can respond
	to one, it is free to discard all but the last event it received.
      </description>
      <arg name="origin_offset_x" type="int"/>
      <arg name="origin_offset_y" type="int"/>
      <arg name="states" type="array"/>
      <arg name="serial" type="uint"/>
    </event>

    <request name="ack_configure" since="5">
      <description summary="ack a configure event">
	When a configure event is received, if a client commits the
	surface in response to the configure event, then the client
	must make an ack_configure request sometime before the commit
	request, passing along the serial of the configure event.

	For instance, the compositor might use this information during display
	configuration to change its coordinate space for set_window_geometry
	requests only when the client has switched to the new coordinate space.

	If the client receives multiple configure events before it
	can respond to one, it only has to ack the last configure event.

	A client is not required to commit immediately after sending
	an ack_configure request - it may even ack_configure several times
	before its next surface commit.

	A client may send multiple ack_configure requests before committing, but
	only the last request sent before a commit indicates which configure
	event the client really is responding to.
      </description>
      <arg name="serial" type="uint" summary="the serial from the configure event"/>
    </request>

    <request name="move" since="5">
      <description summary="start an interactive move">
	[Deprecated] Start an interactive, user-driven move of the surface.

	The compositor responds to this request with a configure event that
	transitions to the "moving" state. The client must only initiate motion
	after acknowledging the state change. The compositor can assume that
	subsequent set_window_geometry requests are position updates until the
	next state transition is acknowledged.

	The compositor may ignore move requests depending on the state of the
	surface, e.g. fullscreen or maximized.
      </description>
    </request>

    <!-- Version 6 additions -->

    <request name="set_orientation" since="6">
      <description summary="set orientation">
	Set an orientation for the surface.
      </description>
      <arg name="orientation" type="int"/>
    </request>

    <!-- Version 7 additions -->

    <request name="set_window_type" since="7">
      <description summary="set the type of the window">
	Set the type of window. This is only a hint to the compositor and the
	compositor is free to ignore it.
      </description>
      <arg name="type" type="uint" summary="type of the window"/>
    </request>

    <!-- Version 9 additions -->

    <request name="resize" since="9">
      <description summary="start an interactive resize">
	[Deprecated] Start an interactive, user-driven resize of the surface.

	The compositor responds to this request with a configure event that
	transitions to the "resizing" state. The client must only initiate
	resizing after acknowledging the state change. The compositor can assume
	that subsequent set_window_geometry requests are resizes until the next
	state transition is acknowledged.

	The compositor may ignore resize requests depending on the state of the
	surface, e.g. fullscreen or maximized.
      </description>
    </request>

    <request name="set_resize_outset" since="9">
      <description summary="expand input region for resizing">
	Expand input region of surface with resize outset.

	The compositor clips the input region of each surface to its bounds,
	unless the client requests a resize outset. In that case, the input
	region of the root surface is expanded to allow for some leeway around
	visible bounds when starting a user-driven resize.
      </description>
      <arg name="outset" type="int"/>
    </request>

    <event name="window_geometry_changed" since="9">
      <description summary="announce window geometry commit">
	Notify the client of committed window geometry.

	The compositor sends this event when it commits window geometry. The
	client may use this information to convert coordinates of input events
	using the latest committed geometry.
      </description>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </event>

    <!-- Version 10 additions -->

    <enum name="bounds_change_reason">
      <description summary="bounds_change_reason">
	Specifies the cause of the window bounds change event.
      </description>
      <entry name="drag_move" value="1" summary="the window is being moved by drag operation"/>
      <entry name="drag_resize" value="2" summary="the window is being resized by drag operation."/>
      <entry name="snap_to_left" value="3"
	     summary="the window is resized to left snapped state"/>
      <entry name="snap_to_right" value="4"
	     summary="the window is resized to right snapped state"/>
      <entry name="move" value="5"
	     summary="the window bounds is moved due to other WM operations"/>
      <entry name="resize" value="6"
	     summary="the window bounds is reiszed due to other WM operations"/>
    </enum>

    <event name="bounds_changed" since="10">
      <description summary="The compositor requested to change the bounds">
	The compositor requested to change its
	bounds. "bounds_change_reason" specifies the cause of the
	bounds change. The client may apply the different move/resize
	strategy depending on the reason.

	"display_id_hi", "display_id_lo" specifies in which workspace
	the surface should live in.

	The client responds with set_window_geometry request, with the
	bounds it is resized to (this may be different from the bounds
	requested).

	The client may ignore move request depending on the state,
	e.g, if it becomes resizable or other constrants.
      </description>
      <arg name="display_id_hi" type="uint"/>
      <arg name="display_id_lo" type="uint"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
      <arg name="bounds_change_reason" type="uint"/>
    </event>

    <request name="start_move" since="10">
      <description summary="start an interactive move">
	Request an interactive, user-driven move of the surface. "x"
	and "y" specifies the starting point of the pointer device
	that initiated the move.

	The compositor responds to this request with a drag_started
	event with "none" direction.  Please see drag_started event
	for more details.

	The compositor may ignore move requests depending on the state of the
	surface, e.g. fullscreen or maximized.
      </description>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
    </request>

    <enum name="resize_direction">
      <description summary="resize direction">
	The resize direction for drag operation
      </description>
      <entry name="none" value="0" summary="move only, no resize"/>
      <entry name="left" value="1" summary="resize to the left"/>
      <entry name="topleft" value="2" summary="resize to the top left"/>
      <entry name="top" value="3" summary="resize to the top"/>
      <entry name="topright" value="4" summary="resize to the top right"/>
      <entry name="right" value="5" summary="resize to the right"/>
      <entry name="bottomright" value="6" summary="resize to the buttom right"/>
      <entry name="bottom" value="7" summary="resize to the bottom"/>
      <entry name="bottomleft" value="8" summary="resize to the bottom left"/>
    </enum>

    <event name="drag_started" since="10">
      <description summary="Notifies that a drag to move/resize started.">
	Notifies a client that the compositor started drag
	operation. "direction" specifies which direction it is being
	resized. "none" direction means just move but not resize.

	This will be followed by series of the "bounds_changed" event
	with "drag_resize" or "drag_move" reasons to update the window
	bounds druing the drag operation.
      </description>
      <arg name="direction" type="uint"/>
    </event>

    <event name="drag_finished" since="10">
      <description summary="Notifies that a drag operation has finished.">
	Called when the drag operation is finished.  "x" and "y"
	specifies the position of the pointer device used to drag.
	"canceled" is true if the drag operation is aborted during
	drag (e.g. by capture change or user action.)
      </description>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="canceled" type="int" summary="true if the operation was canceled"/>
    </event>

    <request name="set_can_maximize" since="10">
      <description summary="set can_maximize">
	Request that surface can be in maximzied state.
      </description>
    </request>

    <request name="unset_can_maximize" since="10">
      <description summary="unset can_maximize">
	Request that surface can not be in maximzied state.
      </description>
    </request>

    <request name="set_min_size" since="10">
      <description summary="set the minimum size">
	Set a minimum size of the surface.

	Values set in this way are double-buffered. They will get
	applied on the next commit.
      </description>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <request name="set_max_size" since="10">
      <description summary="set the maximum size">
	Set a maximum size of the surface.

	Values set in this way are double-buffered. They will get
	applied on the next commit.

	Setting the same size as minimum size makes the surface
	unresizable.
      </description>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <!-- Version 11 additions -->

    <request name="set_snapped_to_left" since="11">
      <description summary="set the surface to left snapped">
	Request that surface is snapped to left.
      </description>
    </request>

    <request name="set_snapped_to_right" since="11">
      <description summary="set the surface to right snapped">
	Request that surface is snapped to right.
      </description>
    </request>

    <!-- Version 12 additions -->

    <request name="start_resize" since="12">
      <description summary="start an interactive resize">
	Request to start an interactive, user-driven resize of the surface.
	"x" and "y" specifies the starting point of the pointer device
	that initiated the reize.

	The compositor responds to this request with a "drag_started"
	event, followed by "bounds_changed" events, and ends the
	resize operation with a "drag_finhsed" event. The compositor
	determines the new bounds using the resize_direction and the
	pointer event location.

	The compositor may ignore resize requests depending on the state of the
	surface, e.g. fullscreen or maximized, or no drag event is in pregress.
      </description>
      <arg name="resize_direction" type="uint" summary="the direction of resize"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
    </request>

    <!-- Version 13 additions -->

    <enum name="frame_type">
      <description summary="frame types">
	Frame type that can be used to decorate a surface.
      </description>
      <entry name="none" value="0" summary="no frame"/>
      <entry name="normal" value="1" summary="caption with shadow" />
      <entry name="shadow" value="2" summary="shadow only"/>
      <entry name="autohide" value="3" summary="autohide frame with shadow"/>
      <entry name="overlay" value="4" summary="overlay frame with shadow" />
    </enum>

    <request name="set_frame" since="13">
      <description summary="request a frame for surface">
	Enables compositor side frame decoration. |type|
	specifies the type of frame to use for the surface.
      </description>
      <arg name="type" type="uint" summary="the frame type"/>
    </request>

    <enum name="frame_button_type">
      <description summary="frame button types">
	The mask that represents buttons on frame.
      </description>
      <entry name="back" value="1" summary="a button to naviate backwards"/>
      <entry name="minimize" value="2" summary="a button to minimize the window"/>
      <entry name="maximize_restore" value="4"
	     summary="a button to maximize or restore"/>
      <entry name="menu" value="8"
	     summary="a button to activate application's menu"/>
      <entry name="close" value="16" summary="a button to close the window"/>
      <entry name="zoom" value="32"
	     summary="a mask to turn the maximize_restore button to zoom button"/>
    </enum>

    <request name="set_frame_buttons" since="13">
      <description summary="updates buttons' state on frame">
	Updates the frame's button state. |visible_buttons| and |enabled_buttons|
	are the union of button mask defined in |frame_button_type| enum.

	The mask present in |enabled_buttons| but not in |visible_buttons| will
	be ignored.
      </description>
      <arg name="visible_buttons" type="uint"/>
      <arg name="enabled_buttons" type="uint"/>
    </request>

    <request name="set_extra_title" since="13">
      <description summary="set extra title string">
	The extra informational string about the surface. This can be
	used to show the debug information in the title bar, or log
	messages.

	This is different from "set_title" which is used to identify
	the surface.

	The string must be encoded in UTF-8.
      </description>
      <arg name="extra_title" type="string"/>
    </request>

    <!-- Version 14 additions -->

    <enum name="orientation_lock">
      <description summary="orientation lock request for remote surfaces">
	Defines orientation request when a remote surface is in foreground.
      </description>
      <entry name="none" value="1" summary="no orientation lock"/>
      <entry name="portrait" value="2" summary="primary or secondary portrait"/>
      <entry name="landscape" value="3" summary="primary or secondary landscape"/>
      <entry name="current" value="4" summary="keep current orientation"/>
      <entry name="portrait_primary" value="5" summary="primary portrait"/>
      <entry name="landscape_primary" value="6" summary="primary landscape"/>
      <entry name="portrait_secondary" value="7" summary="secondary portrait"/>
      <entry name="landscape_secondary" value="8" summary="secondary landscape"/>
    </enum>

    <request name="set_orientation_lock" since="14">
      <description summary="set orientation lock for a remote surface">
	Request a specific orientation behavior when this surface is in foreground.
      </description>
      <arg name="orientation_lock" type="uint" summary="the orientation lock"/>
    </request>

    <!-- Version 15 additions -->

    <request name="pip" since="15">
      <description summary="set pip for a remote surface">
	Request that surface is set to Picture-in-Picture (PIP).
      </description>
    </request>

    <!-- Version 18 additions -->

    <request name="set_bounds" since="18">
      <description summary="set window bounds">
	Set the "visible bounds" of a window from the user's perspective.
	Client-side decorations often have invisible portions like drop shadows
	which should be ignored for the purposes of aligning, placing and
	constraining windows.

	The bounds are double buffered, and will be applied at the
	time wl_surface.commit of the corresponding wl_surface is called.

	Once the bounds are set, it is not possible to unset them, and they will
	remain the same until set_bounds is called again, even if a new sub-
	surface or buffer is attached.

	If never set, the value is the surface content bounds. This updates
	dynamically on every commit.

	The bounds are relative to the given display. If the display is invalid,
	they are assumed to be relative to the primary display.

	The width and height must be greater than zero.
      </description>
      <arg name="display_id_hi" type="uint"/>
      <arg name="display_id_lo" type="uint"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <!-- Version 19 additions -->

    <request name="set_aspect_ratio" since="19">
      <description summary="set the maximum size">
	Set an aspect ratio of the surface.

	Values set in this way are double-buffered. They will get
	applied on the next commit.

	Setting the aspect ratio of the surface. The ratio of the values is used
	for the ratio of width to height of the surface. The size of surface is
	restricted to the ratio. If any value is zero, the restriction on aspect
	ratio is unset.
      </description>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>

    <!-- Version 20 additions -->

    <request name="block_ime" since="20">
      <description summary="block server side IME">
	Block server side IME and always send key events through Wayland.

	For some client, it's possible that server side IME is connected to the
	client through other mechanism e.g. ime.mojom. When set_ime_blocked
	is requested, server side IME should give up handling key events and
	forward those events through Wayland protocol.
      </description>
    </request>

    <request name="unblock_ime" since="20">
      <description summary="unblock host side IME">
	Unblock server side IME. Some events can be handled by server side IME,
	while others can still be sent through Wayland protocol. See the
	description of set_ime_blocked for detail.
      </description>
    </request>
  </interface>

  <interface name="zcr_notification_surface_v1" version="16">
    <description summary="A notification window">
      An interface that may be implemented by a wl_surface to host
      notification contents.
    </description>

    <request name="destroy" type="destructor">
      <description summary="Destroy the notification_surface">
	Unmap and destroy the notification surface.
      </description>
    </request>

    <!-- Version 16 additions -->

    <request name="set_app_id" since="16">
      <description summary="set application ID">
	Set an application identifier for the notification surface.
      </description>
      <arg name="app_id" type="string"/>
    </request>
  </interface>

  <interface name="zcr_input_method_surface_v1" version="18">
    <description summary="An input method window">
      An interface that may be implemented by a wl_surface to host IME contents.
    </description>

    <request name="destroy" type="destructor">
      <description summary="Destroy the ime_surface">
	Unmap and destroy the input mtehod surface.
      </description>
    </request>

    <!-- Version 18 additions -->

    <request name="set_bounds" since="18">
      <description summary="set window bounds">
	Set the "visible bounds" of a window from the user's perspective.

	The bounds are double buffered, and will be applied at the
	time wl_surface.commit of the corresponding wl_surface is called.

	Once the bounds are set, it is not possible to unset them, and they will
	remain the same until set_bounds is called again, even if a new sub-
	surface or buffer is attached.

	If never set, the value is the surface content bounds. This updates
	dynamically on every commit.

	The bounds are relative to the given display. If the display is invalid,
	they are assumed to be relative to the primary display.

	The width and height must be greater than zero.
      </description>
      <arg name="display_id_hi" type="uint"/>
      <arg name="display_id_lo" type="uint"/>
      <arg name="x" type="int"/>
      <arg name="y" type="int"/>
      <arg name="width" type="int"/>
      <arg name="height" type="int"/>
    </request>
  </interface>

</protocol>