From e38f433313e7c13960fb06f2b761f324010b8d64 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 30 Mar 2013 01:11:38 -0400 Subject: [PATCH] docs: Improve wl_shell/wl_shell_surface docs Add missing summaries, expand descriptions. --- protocol/wayland.xml | 233 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 149 insertions(+), 84 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 2417c0e..a3599f0 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -597,7 +597,20 @@ + + 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. + + + + Create a shell surface for an existing surface. + + Only one shell surface can be associated with a given surface. + @@ -605,11 +618,18 @@ - - An interface implemented by a wl_surface. On 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. + + An interface that may be implemented by a wl_surface, for + implementations that provide a desktop-style user interface. + + 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. @@ -617,15 +637,28 @@ A client must respond to a ping event with a pong request or the client may be deemed unresponsive. - + - - + + 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). + + + + + 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. + @@ -638,31 +671,43 @@ - - - + + Start a pointer-driven resizing of the surface. + + 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). + + + + - - Make the surface a toplevel window. + + Map the surface as a toplevel surface. + + A toplevel surface is not fullscreen, maximized or transient. + + These flags specify details of the expected behaviour + of transient surfaces. Used in the set_transient request. + - Map the surface relative to an existing surface. The x and y - arguments specify the locations of the upper left corner of - the surface relative to the upper left corner of the parent - surface. The flags argument controls overflow/clipping - behaviour when the surface would intersect a screen edge, - panel or such. And possibly whether the offset only - determines the initial position or if the surface is locked to - that relative position during moves. + Map the surface relative to an existing surface. + + The x and y arguments specify the locations of the upper left + corner of the surface relative to the upper left corner of the + parent surface. + + The flags argument controls details of the transient behaviour. @@ -671,75 +716,67 @@ + + + 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. + + + + + + + - Map the surface as a fullscreen surface. If an output parameter is - 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. + Map the surface as a fullscreen surface. - The client may specify a method to resolve a size conflict between the - output size and the surface size - this is provided through the - fullscreen_method parameter. + If an output parameter is 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 framerate parameter is used only when the fullscreen_method is set - to "driver", to indicate the preferred framerate. framerate=0 indicates - that the app does not care about framerate. The framerate is - specified in mHz, that is framerate of 60000 is 60Hz. + The client may specify a method to resolve a size conflict + between the output size and the surface size - this is provided + through the method parameter. - 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. + The framerate parameter is used only when the method is set + 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. - - - 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. + + + Map the surface as a popup. - "scale" The client prefers scaling by the compositor. Scaling would - always preserve surface's aspect ratio with surface centered on the - output + A popup surface is a transient surface with an added pointer + grab. - "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. + 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). - "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. - - - - - - - - - - Popup surfaces. Will switch an implicit grab into - owner-events mode, and grab will continue after the implicit - grab ends (button released). Once the implicit grab is over, - the popup grab continues until the window is destroyed or a - mouse button is pressed in any other clients window. A click + 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, clicks in other clients surfaces will be discarded and trigger the callback. - - TODO: Grab keyboard too, maybe just terminate on any click - inside or outside the surface? - - + + @@ -748,29 +785,49 @@ - A request from the client to notify the compositor the maximized - operation. 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 client will fill the fullscreen of the output it is bound - to, except the panel area. This is the main difference between - a maximized shell surface and a fullscreen shell surface. + Map the surface as a maximized surface. + + If an output parameter is given then the surface will be + maximized 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 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. + 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. + Set a class for the surface. + The surface class identifies the general class of applications - to which the surface belongs. The class is the file name of - the applications .desktop file (absolute path if non-standard - location). + to which the surface belongs. A common convention is to use + the file name (full path if non-standard location) of the + applications .desktop file as the class. @@ -786,11 +843,19 @@ The configure event asks the client to resize its surface. + 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 - satisfy aspect ratio or resize in steps of NxM pixels). The - client is free to dismiss all but the last configure event it - received. + satisfy aspect ratio or resize in steps of NxM pixels). + + 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. -- 2.7.4