mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2025-11-25 06:59:46 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Improve wl_shell/wl_shell_surface docs

Browse source 
Add missing summaries, expand descriptions.
This commit is contained in:
Matthias Clasen 2013-03-30 01:11:38 -04:00 • committed by Kristian Høgsberg
parent 15ec6219e9
commit e38f433313
1 changed files with 150 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

235
protocol/wayland.xml
View file

@ -597,7 +597,20 @@
</interface> </interface>
<interface name="wl_shell" version="1"> <interface name="wl_shell" version="1">
<description summary="create desktop-style surfaces">
This interface is implemented by servers that provide
desktop-style user interfaces.
It allows clients to associate a wl_shell_surface with
a basic surface.
</description>
<request name="get_shell_surface"> <request name="get_shell_surface">
<description summary="create a shell surface from a surface">
Create a shell surface for an existing surface.
Only one shell surface can be associated with a given surface.
</description>
<arg name="id" type="new_id" interface="wl_shell_surface"/> <arg name="id" type="new_id" interface="wl_shell_surface"/>
<arg name="surface" type="object" interface="wl_surface"/> <arg name="surface" type="object" interface="wl_surface"/>
</request> </request>
@ -605,11 +618,18 @@
<interface name="wl_shell_surface" version="1"> <interface name="wl_shell_surface" version="1">
<description summary="desktop style meta data interface"> <description summary="desktop-style metadata interface">
An interface implemented by a wl_surface. On server side the An interface that may be implemented by a wl_surface, for
object is automatically destroyed when the related wl_surface is implementations that provide a desktop-style user interface.
destroyed. On client side, wl_shell_surface_destroy() must be
called before destroying the wl_surface object. It provides requests to treat surfaces like toplevel, fullscreen
or popup windows, move, resize or maximize them, associate
metadata like title and class, etc.
On the server side the object is automatically destroyed when
the related wl_surface is destroyed. On client side,
wl_shell_surface_destroy() must be called before destroying
the wl_surface object.
</description> </description>
<request name="pong"> <request name="pong">
@ -617,15 +637,28 @@
A client must respond to a ping event with a pong request or A client must respond to a ping event with a pong request or
the client may be deemed unresponsive. the client may be deemed unresponsive.
</description> </description>
<arg name="serial" type="uint"/> <arg name="serial" type="uint" summary="serial of the ping event"/>
</request> </request>
<request name="move"> <request name="move">
<arg name="seat" type="object" interface="wl_seat"/> <description summary="start an interactive move">
<arg name="serial" type="uint"/> Start a pointer-driven move of the surface.
This request must be used in response to a button press event.
The server may ignore move requests depending on the state of
the surface (e.g. fullscreen or maximized).
</description>
<arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
<arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
</request> </request>
<enum name="resize"> <enum name="resize">
<description summary="edge values for resizing">
These values are used to indicate which edge of a surface
is being dragged in a resize operation. The server may
use this information to adapt its behavior, e.g. choose
an appropriate cursor image.
</description>
<entry name="none" value="0"/> <entry name="none" value="0"/>
<entry name="top" value="1"/> <entry name="top" value="1"/>
<entry name="bottom" value="2"/> <entry name="bottom" value="2"/>
@ -638,31 +671,43 @@
</enum> </enum>
<request name="resize"> <request name="resize">
<arg name="seat" type="object" interface="wl_seat"/> <description summary="start an interactive resize">
<arg name="serial" type="uint"/> Start a pointer-driven resizing of the surface.
<arg name="edges" type="uint"/>
This request must be used in response to a button press event.
The server may ignore resize requests depending on the state of
the surface (e.g. fullscreen or maximized).
</description>
<arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
<arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
<arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
</request> </request>
<request name="set_toplevel"> <request name="set_toplevel">
<description summary="make the surface a top level surface"> <description summary="make the surface a toplevel surface">
Make the surface a toplevel window. Map the surface as a toplevel surface.
A toplevel surface is not fullscreen, maximized or transient.
</description> </description>
</request> </request>
<enum name="transient"> <enum name="transient">
<description summary="details of transient behaviour">
These flags specify details of the expected behaviour
of transient surfaces. Used in the set_transient request.
</description>
<entry name="inactive" value="0x1" summary="do not set keyboard focus"/> <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
</enum> </enum>
<request name="set_transient"> <request name="set_transient">
<description summary="make the surface a transient surface"> <description summary="make the surface a transient surface">
Map the surface relative to an existing surface. The x and y Map the surface relative to an existing surface.
arguments specify the locations of the upper left corner of
the surface relative to the upper left corner of the parent The x and y arguments specify the locations of the upper left
surface. The flags argument controls overflow/clipping corner of the surface relative to the upper left corner of the
behaviour when the surface would intersect a screen edge, parent surface.
panel or such. And possibly whether the offset only
determines the initial position or if the surface is locked to The flags argument controls details of the transient behaviour.
that relative position during moves.
</description> </description>
<arg name="parent" type="object" interface="wl_surface"/> <arg name="parent" type="object" interface="wl_surface"/>
@ -671,75 +716,67 @@
<arg name="flags" type="uint"/> <arg name="flags" type="uint"/>
</request> </request>
<enum name="fullscreen_method">
<description summary="different method to set the surface fullscreen">
Hints to indicate to the compositor how to deal with a conflict
between the dimensions of the surface and the dimensions of the
output. The compositor is free to ignore this parameter.
</description>
<entry name="default" value="0" summary="no preference, apply default policy"/>
<entry name="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/>
<entry name="driver" value="2" summary="switch output mode to the smallest mode that can fit the surface, add black borders to compensate size mismatch"/>
<entry name="fill" value="3" summary="no scaling, center on output and add black borders to compensate size mismatch"/>
</enum>
<request name="set_fullscreen"> <request name="set_fullscreen">
<description summary="make the surface a fullscreen surface"> <description summary="make the surface a fullscreen surface">
Map the surface as a fullscreen surface. If an output parameter is Map the surface as a fullscreen surface.
given then the surface will be made fullscreen on that output. If the
client does not specify the output then the compositor will apply its
policy - usually choosing the output on which the surface has the
biggest surface area.
The client may specify a method to resolve a size conflict between the If an output parameter is given then the surface will be made
output size and the surface size - this is provided through the fullscreen on that output. If the client does not specify the
fullscreen_method parameter. output then the compositor will apply its policy - usually
choosing the output on which the surface has the biggest surface
area.
The framerate parameter is used only when the fullscreen_method is set The client may specify a method to resolve a size conflict
to "driver", to indicate the preferred framerate. framerate=0 indicates between the output size and the surface size - this is provided
that the app does not care about framerate. The framerate is through the method parameter.
specified in mHz, that is framerate of 60000 is 60Hz.
The compositor must reply to this request with a configure event with The framerate parameter is used only when the method is set
the dimensions for the output on which the surface will be made fullscreen. to "driver", to indicate the preferred framerate. A value of 0
indicates that the app does not care about framerate. The
framerate is specified in mHz, that is framerate of 60000 is 60Hz.
The compositor must reply to this request with a configure event
with the dimensions for the output on which the surface will
be made fullscreen.
</description> </description>
<arg name="method" type="uint"/> <arg name="method" type="uint"/>
<arg name="framerate" type="uint"/> <arg name="framerate" type="uint"/>
<arg name="output" type="object" interface="wl_output" allow-null="true"/> <arg name="output" type="object" interface="wl_output" allow-null="true"/>
</request> </request>
<enum name="fullscreen_method">
<description summary="different method to set the surface fullscreen">
Hints to indicate compositor how to deal with a conflict between the
dimensions for the surface and the dimensions of the output. As a hint
the compositor is free to ignore this parameter.
"default" The client has no preference on fullscreen behavior,
policies are determined by compositor.
"scale" The client prefers scaling by the compositor. Scaling would
always preserve surface's aspect ratio with surface centered on the
output
"driver" The client wants to switch video mode to the smallest mode
that can fit the client buffer. If the sizes do not match the
compositor must add black borders.
"fill" The surface is centered on the output on the screen with no
scaling. If the surface is of insufficient size the compositor must
add black borders.
</description>
<entry name="default" value="0"/>
<entry name="scale" value="1"/>
<entry name="driver" value="2"/>
<entry name="fill" value="3"/>
</enum>
<request name="set_popup"> <request name="set_popup">
<description summary="make the surface a popup surface"> <description summary="make the surface a popup surface">
Popup surfaces. Will switch an implicit grab into Map the surface as a popup.
owner-events mode, and grab will continue after the implicit
grab ends (button released). Once the implicit grab is over, A popup surface is a transient surface with an added pointer
the popup grab continues until the window is destroyed or a grab.
mouse button is pressed in any other clients window. A click
An existing implicit grab will be changed to owner-events mode,
and the popup grab will continue after the implicit grab ends
(i.e. releasing the mouse button does not cause the popup to
be unmapped).
The popup grab continues until the window is destroyed or a
mouse button is pressed in any other clients window. A click
in any of the clients surfaces is reported as normal, however, in any of the clients surfaces is reported as normal, however,
clicks in other clients surfaces will be discarded and trigger clicks in other clients surfaces will be discarded and trigger
the callback. the callback.
TODO: Grab keyboard too, maybe just terminate on any click
inside or outside the surface?
</description> </description>
<arg name="seat" type="object" interface="wl_seat"/> <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
<arg name="serial" type="uint"/> <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
<arg name="parent" type="object" interface="wl_surface"/> <arg name="parent" type="object" interface="wl_surface"/>
<arg name="x" type="int"/> <arg name="x" type="int"/>
<arg name="y" type="int"/> <arg name="y" type="int"/>
@ -748,29 +785,49 @@
<request name="set_maximized"> <request name="set_maximized">
<description summary="make the surface a maximized surface"> <description summary="make the surface a maximized surface">
A request from the client to notify the compositor the maximized Map the surface as a maximized surface.
operation. The compositor will reply with a configure event telling
the expected new surface size. The operation is completed on the If an output parameter is given then the surface will be
next buffer attach to this surface. maximized on that output. If the client does not specify the
A maximized client will fill the fullscreen of the output it is bound output then the compositor will apply its policy - usually
to, except the panel area. This is the main difference between choosing the output on which the surface has the biggest surface
a maximized shell surface and a fullscreen shell surface. area.
The compositor will reply with a configure event telling
the expected new surface size. The operation is completed
on the next buffer attach to this surface.
A maximized surface typically fills the entire output it is
bound to, except for desktop element such as panels. This is
the main difference between a maximized shell surface and a
fullscreen shell surface.
The details depend on the compositor implementation.
</description> </description>
<arg name="output" type="object" interface="wl_output" allow-null="true"/> <arg name="output" type="object" interface="wl_output" allow-null="true"/>
</request> </request>
<request name="set_title"> <request name="set_title">
<description summary="set surface 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> </description>
<arg name="title" type="string"/> <arg name="title" type="string"/>
</request> </request>
<request name="set_class"> <request name="set_class">
<description summary="set surface class"> <description summary="set surface class">
Set a class for the surface.
The surface class identifies the general class of applications The surface class identifies the general class of applications
to which the surface belongs. The class is the file name of to which the surface belongs. A common convention is to use
the applications .desktop file (absolute path if non-standard the file name (full path if non-standard location) of the
location). applications .desktop file as the class.
</description> </description>
<arg name="class_" type="string"/> <arg name="class_" type="string"/>
</request> </request>
@ -786,11 +843,19 @@
<event name="configure"> <event name="configure">
<description summary="suggest resize"> <description summary="suggest resize">
The configure event asks the client to resize its surface. The configure event asks the client to resize its surface.
The size is a hint, in the sense that the client is free to The size is a hint, in the sense that the client is free to
ignore it if it doesn't resize, pick a smaller size (to ignore it if it doesn't resize, pick a smaller size (to
satisfy aspect ratio or resize in steps of NxM pixels). The satisfy aspect ratio or resize in steps of NxM pixels).
client is free to dismiss all but the last configure event it
received. The edges parameter provides a hint about how the surface
was resized. The client may use this information to decide
how to adjust its content to the new size (e.g. a scrolling
area might adjust its content position to leave the viewable
content unmoved).
The client is free to dismiss all but the last configure
event it received.
</description> </description>
<arg name="edges" type="uint"/> <arg name="edges" type="uint"/>