[PATCH] xdg-shell - yet another proposal (this time for real).

[Rafael Antognolli]

Hello all,

Following is the same description as in my previous wrong email, but with the
correct patch attached.

I'm trying to summarize part of the discussion in this new patch, but it's not
the final one.

As far as I understood, the goal is to end up with something like this for
keyboard focus:

W = compositor
A, Z = client surfaces

Viewport change:
W to Z: You are deactivated.
W to A: You are activated.
A to W: Do these things.

So, I added "activated" and "deactivated" events, that the compositor can use
to inform clients what they are. And there's a take_focus request that can be
used by a client to ask for activation, but it's up to the compositor to
decide.

Regarding the surface fullscreen, maximized, etc, I added surface states as
enum's, that can be set/unset, and events from the compositor to request that a
given state should be set/unset.

For those states that take parameters, I added separate requests for setting
the parameters before setting the state. It should all take place after commit
anyway, so that shouldn't matter much. Take a look at the docs and say what you
think.

I didn't change transient/popup surface types yet, but from what has been said
in the ML thread, I think they also should be surface states now. Correct me if
I'm wrong. Otherwise I'm going to send an updated version with those changes
tomorrow.

I also talked to jekstrand (I think) about stacking, will send an updated
version with what I understood from that tomorrow. Should be simple.

Any feedback is appreciated, and thank you guys for the input so far and the
patience.


Rafael Antognolli (1):
xdg_shell: Add a new shell protocol.

protocol/Makefile.am | 2 +-
protocol/xdg-surface.xml | 381 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 382 insertions(+), 1 deletion(-)
create mode 100644 protocol/xdg-surface.xml

[Rafael Antognolli]

xdg_shell is a protocol aimed to substitute wl_shell in the long term,
but will not be part of the wayland core protocol. It starts as a
non-stable API, aimed to be used as a development place at first, and
once features are defined as required by several desktop shells, we can
finally make it stable.
---
protocol/Makefile.am | 2 +-
protocol/xdg-surface.xml | 381 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 382 insertions(+), 1 deletion(-)
create mode 100644 protocol/xdg-surface.xml

diff --git a/protocol/Makefile.am b/protocol/Makefile.am
index e8b6290..9d27a2d 100644
--- a/protocol/Makefile.am
+++ b/protocol/Makefile.am
@@ -1,4 +1,4 @@
-dist_pkgdata_DATA = wayland.xml wayland.dtd
+dist_pkgdata_DATA = wayland.xml wayland.dtd xdg-surface.xml

if HAVE_XMLLINT
.PHONY: validate
diff --git a/protocol/xdg-surface.xml b/protocol/xdg-surface.xml
new file mode 100644
index 0000000..8e29751
--- /dev/null
+++ b/protocol/xdg-surface.xml
@@ -0,0 +1,381 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_surface">
+
+ <copyright>
+ Copyright ? 2008-2013 Kristian H?gsberg
+ Copyright ? 2013 Rafael Antognolli
+ Copyright ? 2010-2013 Intel Corporation
+
+ Permission to use, copy, modify, distribute, and sell this
+ software and its documentation for any purpose is hereby granted
+ without fee, provided that the above copyright notice appear in
+ all copies and that both that copyright notice and this permission
+ notice appear in supporting documentation, and that the name of
+ the copyright holders not be used in advertising or publicity
+ pertaining to distribution of the software without specific,
+ written prior permission. The copyright holders make no
+ representations about the suitability of this software for any
+ purpose. It is provided "as is" without express or implied
+ warranty.
+
+ THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+ SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ SPECIAL, 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>
+
+ <interface name="xdg_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 xdg_surface with
+ a basic surface.
+ </description>
+
+ <request name="get_xdg_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="xdg_surface"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+ </interface>
+
+ <interface name="xdg_surface" version="1">
+
+ <description summary="desktop-style metadata interface">
+ 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,
+ xdg_surface_destroy() must be called before destroying
+ the wl_surface object.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="remove xdg_surface interface">
+ The xdg_surface interface is removed from the wl_surface object
+ that was turned into a xdg_surface with
+ xdg_shell.get_xdg_surface request. The xdg_surface properties,
+ like maximized and fullscreen, are lost. The wl_surface loses
+ its role as a xdg_surface. The wl_surface is unmapped.
+ </description>
+ </request>
+
+ <request name="pong">
+ <description summary="respond to a ping event">
+ A client must respond to a ping event with a pong request or
+ the client may be deemed unresponsive.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the ping event"/>
+ </request>
+
+ <request name="move">
+ <description summary="start an interactive move">
+ 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"/>
+ <art name="cursor_surface" type="object" interface="wl_surface" summary="the cursor surface used during the movement"/>
+ </request>
+
+ <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="top" value="1"/>
+ <entry name="bottom" value="2"/>
+ <entry name="left" value="4"/>
+ <entry name="top_left" value="5"/>
+ <entry name="bottom_left" value="6"/>
+ <entry name="right" value="8"/>
+ <entry name="top_right" value="9"/>
+ <entry name="bottom_right" value="10"/>
+ </enum>
+
+ <request name="resize">
+ <description summary="start an interactive resize">
+ 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).
+ </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"/>
+ <art name="cursor_surface" type="object" interface="wl_surface" summary="the cursor surface used during the resizing"/>
+ </request>
+
+ <request name="set_toplevel">
+ <description summary="make the surface a toplevel surface">
+ Map the surface as a toplevel surface.
+
+ A toplevel surface is not transient or popup. It supports
+ surface states though, like maximized, minimized and fullscreen.
+ </description>
+ </request>
+
+ <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"/>
+ </enum>
+
+ <request name="set_transient">
+ <description summary="make the surface a transient surface">
+ 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, in surface local coordinates.
+
+ The flags argument controls details of the transient behaviour.
+ </description>
+
+ <arg name="parent" type="object" interface="wl_surface"/>
+ <arg name="flags" type="uint"/>
+ </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 upscaling, center on output and add black borders to compensate size mismatch"/>
+ </enum>
+
+ <request name="set_popup">
+ <description summary="make the surface a popup surface">
+ Map the surface as a popup.
+
+ A popup surface is a transient surface with an added pointer
+ grab.
+
+ 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,
+ clicks in other clients surfaces will be discarded and trigger
+ the callback.
+
+ 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, in surface local coordinates.
+ </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="parent" type="object" interface="wl_surface"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="flags" type="uint"/>
+ </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_class">
+ <description summary="set surface class">
+ Set a class for the surface.
+
+ The surface class identifies the general class of applications
+ 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.
+ </description>
+ <arg name="class_" type="string"/>
+ </request>
+
+ <enum name="state">
+ <description summary="surface states">
+ Basic window states that can be set/unset by the client, and/or
+ requested by the compositor.
+ </description>
+ <entry name="maximized" value="0" summary="surface is maximized"/>
+ <entry name="fullscreen" value="1" summary="surface is fullscreen"/>
+ <entry name="minimized" value="2" summary="surface is minimized"/>
+ <entry name="always_above" value="3" summary="surface is always on top"/>
+ <entry name="always_below" value="4" summary="surface is always below"/>
+ <entry name="sticky" value="5" summary="surface is visible on all desktops"/>
+ </enum>
+
+ <request name="state_set">
+ <description summary="set the surface state">
+ Set the surface state.
+ </description>
+ <arg name="state" type="uint"/>
+ </request>
+
+ <request name="state_unset">
+ <description summary="set the surface state">
+ Unset the surface state.
+ </description>
+ <arg name="state" type="uint"/>
+ </request>
+
+ <request name="set_fullscreen_method">
+ <description summary="set the fullscreen method used by this surface">
+ The fullscreen method set here will be used when the surface state is
+ set to fullscreen.
+
+ This call has no effect on non-fullscreen surfaces, but the method set
+ here will be used later if the surface ever becomes fullscreen. If the
+ surface is already in a fullscreen state, it will start using this
+ method, instead of the current one.
+
+ Default is (?).
+ </description>
+ <arg name="method" type="uint"/>
+ </request>
+
+ <request name="set_fullscreen_framerate">
+ <description summary="set the fullscreen framerate used by this surface">
+ See set_fullscreen_method above.
+ </description>
+ <arg name="framerate" type="uint"/>
+ </request>
+
+ <request name="set_output">
+ <description summary="set the default output used by this surface">
+ Set the default output used by this surface when it is first mapped.
+
+ If this value is NULL (default), it's up to the compositor to choose
+ which display will be used to map this surface.
+
+ When fullscreen state is set on this surface, the output set with this
+ method will be used. Otherwise, the output where the surface is
+ currently mapped will be used.
+
+ Same for maximized state.
+ </description>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+ </request>
+
+ <request name="demands_attention">
+ <description summary="surface demanding attention">
+ The demands_attention request indicates that activity has
+ occurred in the surface that is important to the client. It
+ informs the compositor that the user should be informed about
+ this surface alert.
+ </description>
+ </request>
+
+ <request name="take_focus">
+ <description summary="take keyboard focus">
+ The surface request keyboard focus to itself. The compositor
+ will likely give keyboard focus to that surface.
+ </description>
+ </request>
+
+ <event name="ping">
+ <description summary="ping client">
+ Ping a client to check if it is receiving events and sending
+ requests. A client is expected to reply with a pong request.
+ </description>
+ <arg name="serial" type="uint"/>
+ </event>
+
+ <event name="configure">
+ <description summary="suggest resize">
+ 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 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.
+
+ The width and height arguments specify the size of the window
+ in surface local coordinates.
+ </description>
+
+ <arg name="edges" type="uint"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
+
+ <event name="popup_done">
+ <description summary="popup interaction is done">
+ The popup_done event is sent out when a popup grab is broken,
+ that is, when the users clicks a surface that doesn't belong
+ to the client owning the popup surface.
+ </description>
+ </event>
+
+ <event name="activated">
+ <description summary="surface was activated">
+ The activated event is sent when this surface has been
+ activated, by clicking or touching or alt-tabbing (or hovering
+ in case of sloppy focus).
+
+ The surface has received keyboard focus.
+ </description>
+ </event>
+
+ <event name="deactivated">
+ <description summary="surface was activated">
+ The activate event is sent when this surface has been deactivated,
+ because another surface has been activated.
+
+ When this event is received, the surface no longer has keyboard
+ focus. If necessary, the surface can request keyboard focus
+ again by calling xdg_surface.take_focus.
+ </description>
+ </event>
+
+ <event name="state_update">
+ <description summary="surface should be maximized">
+ </description>
+ <arg name="state" type="uint"/>
+ <arg name="enabled" type="uint"/>
+ </event>
+ </interface>
+</protocol>

[Bill Spitzak]

Post by Rafael Antognolli
So, I added "activated" and "deactivated" events, that the compositor can use
to inform clients what they are. And there's a take_focus request

Shouldn't that be called a "take_active" request?

I can think of scenarios where it would be useful to get the keyboard
focus but not activation. I believe there is no need to support this
initially, as *becoming* active can always mean the client gets the
focus. But there may need to be a way for a client to take_focus without
becoming active.

The scenarios I see this being useful:

To not activate on a drag & drop in point-to-type: a client could send
only a "take_focus" when the mouse enters it. It does an activate only
on a mouse-click or keystroke that does *not* start a drag.

To support OS/X style menubars with point-to-type or when click does not
raise surfaces: clients might take the key focus on enter/click, but not
activate until the user types a keystroke. Thus the user can move the
mouse to the menubar in a point-to-type system without the menubar
changing, and can click in background windows without the menubar changing.

[Rafael Antognolli]

Hi Bill and Gregory,

So, I talked to Kristian and Jasper on IRC, and we decided to follow a
simpler route, of just adding what is strictly necessary for us right
now. I'm going to send another protocol xml proposal again, on a
following email, but this time without the activate/deactivate part, or
any stacking related requests or events.

The idea is that we start working to get this proposal implemented asap,
and then we can take care of these other, more complicated details. This
new proposal does not prevent us from adding the extra complexity for
activation and stacking later, and the protocol is totally
unstable/experimental (would be called egg_shell for that, but we just
left it as xdg_shell).

Post by Bill Spitzak

Post by Rafael Antognolli
So, I added "activated" and "deactivated" events, that the compositor can use
to inform clients what they are. And there's a take_focus request

Shouldn't that be called a "take_active" request?
I can think of scenarios where it would be useful to get the keyboard focus
but not activation. I believe there is no need to support this initially, as
*becoming* active can always mean the client gets the focus. But there may
need to be a way for a client to take_focus without becoming active.
To not activate on a drag & drop in point-to-type: a client could send only
a "take_focus" when the mouse enters it. It does an activate only on a
mouse-click or keystroke that does *not* start a drag.
To support OS/X style menubars with point-to-type or when click does not
raise surfaces: clients might take the key focus on enter/click, but not
activate until the user types a keystroke. Thus the user can move the mouse
to the menubar in a point-to-type system without the menubar changing, and
can click in background windows without the menubar changing.
_______________________________________________
wayland-devel mailing list
wayland-devel at lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[Rafael Antognolli]

Hi Bill and Gregory,

So, I talked to Kristian and Jasper on IRC, and we decided to follow a
simpler route, of just adding what is strictly necessary for us right
now. I'm going to send another protocol xml proposal again, on a
following email, but this time without the activate/deactivate part, or
any stacking related requests or events.

The idea is that we start working to get this proposal implemented asap,
and then we can take care of these other, more complicated details. This
new proposal does not prevent us from adding the extra complexity for
activation and stacking later, and the protocol is totally
unstable/experimental (would be called egg_shell for that, but we just
left it as xdg_shell).

I'll get back to the activation discussion in a bit. And thanks a lot so
far fo the input.

Post by Bill Spitzak

Post by Rafael Antognolli
So, I added "activated" and "deactivated" events, that the compositor can use
to inform clients what they are. And there's a take_focus request

Shouldn't that be called a "take_active" request?
I can think of scenarios where it would be useful to get the keyboard focus
but not activation. I believe there is no need to support this initially, as
*becoming* active can always mean the client gets the focus. But there may
need to be a way for a client to take_focus without becoming active.
To not activate on a drag & drop in point-to-type: a client could send only
a "take_focus" when the mouse enters it. It does an activate only on a
mouse-click or keystroke that does *not* start a drag.
To support OS/X style menubars with point-to-type or when click does not
raise surfaces: clients might take the key focus on enter/click, but not
activate until the user types a keystroke. Thus the user can move the mouse
to the menubar in a point-to-type system without the menubar changing, and
can click in background windows without the menubar changing.

[Gregory Merchan]

I failed to reply to all. I hope copying and pasting hasn't messed up anything.

On Thu, Nov 7, 2013 at 3:32 AM, Rafael Antognolli

Post by Rafael Antognolli
Hello all,
Following is the same description as in my previous wrong email, but with the
correct patch attached.
I'm trying to summarize part of the discussion in this new patch, but it's not
the final one.
As far as I understood, the goal is to end up with something like this for
W = compositor
A, Z = client surfaces
W to Z: You are deactivated.
W to A: You are activated.
A to W: Do these things.
So, I added "activated" and "deactivated" events, that the compositor can use
to inform clients what they are. And there's a take_focus request that can be
used by a client to ask for activation, but it's up to the compositor to
decide.

That's only part of it. When I wrote about W, A, and Z, the discussion
had been narrowed to a subset of reasons for changing focus that
included things like viewport changes.

The name "take_focus" sounds like it's about something different from
"activated" and "deactivated". It's is also similar to a request on X
which window managers make of clients, "WM_TAKE_FOCUS", and this
invites confusion. It also sounds more like a request to deactivate,
as in, "Please take focus away from me."

The obvious name for the request, "activate", is only one letter
different from the name of the event "activated", so perhaps that
should be avoided. I think "set_active" is in line with other names.
If that's not suitable, only "please_activate" and "make_active" come
to my mind. I will use "set_active" for the remainder of this message.

I described the need for signatures allowing the compositor to
validate requests. I believe the simplest suitable signature is a
timestamp as provided by some events. This allows the compositor to
associate the request with an event and to invalidate requests which
have been superseded by later requests. The timestamp of
wl_pointer::button and other user-generated events seems to be the
thing to use.

The "activated" event must provide a valid timestamp which the client
can use as a signature to make a "set_active" request. This allows the
client to activate the correct surface (such as a modal dialog) when
the compositor has activated the wrong surface. The "deactivated"
event does not really need a timestamp, because merely being
deactivated is no reason to request activation, but clients could use
such a timestamp to avoid making requests which will fail because
their timestamps came before the deactivation. The name and type of
the timestamp should be "time" and "uint", just like the
user-generated wl_pointer::button, wl_keyboard::key, and
wl_touch::down events.

The "set_active" request should have a "time" argument of type "uint",
just like the aforementioned events.

These events, requests, and timestamps do not suffice to make a good
system; a good division of responsibilities is also needed. The only
division of responsibilities which allows for all of the expected
features of modern GUIs is as follows.

Clients:
1. Must request activation when they need it, as indicated by
user-generated events or other sources of timestamps.
2. Must expect activation from the compositor, which will happen for
events of which clients cannot be aware.

Compositors:
3. Must not activate surfaces when clients could request activation
but have not done so.
4. May activate surfaces in response to requests or events of which
clients are not aware.

You may note that this is different from what MS Windows and all
extant X11 window managers do; it is at least similar to what MacOS
does.

Why this division? I'll go through each.

1.
A. When the user presses a button over a client surface, only that
client is aware of the contents of the surface and thus whether the
surface should remain inactive or be activated. If the button press is
on something in the surface that might be dragged to another surface,
such as file icon, a client would remain inactive so as not to be
raised and obscure the drop target. If the button press is on a
control that could be used without changing keyboard focus, like a
tool palette or a scroll bar, a client would remain inactive to allow
other work to proceed without moving keyboard focus back and forth.
B. Events may occur in other clients, and not the compositor, which
provide a client with a reason to request activation. The most obvious
is when one client starts another client, as a file manager might
start a text editor to open a document. The starting client should
provide to the started client the timestamp of the event which is the
reason for starting it, and then the started client should request
activation using that timestamp when it is ready to do so. This allows
for a smooth flow of work between applications. Because clients can
only request activation, the compositor, checking timestamps, can
prevent a client which took too long to start from stealing activation
from a client that was activated during the delay.
C. Clients may need to request activation when they already have it.
Using the file manager example again, if the user decides to not to
wait on a slow loading application and instead does something else
with the file manager, the file manager, even though active, should
again request activation so the compositor will have a last activation
timestamp more recent than the one the slow app will use. Such a
technique may be used in terminal emulators so that applications
opened from a command line do not steal activation from the terminal
if the user continues to use the terminal. If the pointer leaves an
activated surface, enters it again, and a button is pressed, the
client should again request activation of the still active surface, so
that slow clients, seeking activation from when the active client lost
pointer focus, do not steal activation. (Perhaps I should write an
essay, "Has your activation gone stale? Preventing activation
stealing.")

2. The compositor is the final arbiter of activation and may deem it
necessary despite the expectations of a client. Clients cannot refuse
activation, but they are not without options in response to it. They
may: a) request another of their surfaces be activated, using the
timestamp from the "activated" event; b) destroy the surface; or c)
ignore activation by not repainting their windows, processing
keystrokes, etc. (This last option is not recommended.) Clients should
not delay their responses in an attempt to second-guess the
compositor.

3. If a compositor activates a surface when a client could just as
well request activation, it will prevent more sophisticated
interactions such as raise-less drag-and-drop, fluid palette use, and
churn-free scrolling. I may also cause focus stealing by errantly
activating new surfaces. Clients creating new surfaces, even new
clients, should be requesting activation with timestamps provided by
events or other clients. A new client without a timestamp to activate
its surfaces should use "demands_attention" instead.

4. There are events which clients do not receive but nonetheless are a
reason for client surfaces to be activated. The destruction of another
client's surface, a viewport change, and window switching by keystroke
(Alt+Tab), are examples of such events. For these, if a surface is to
be activated, it must be the compositor which does so despite no
request from the client. Because the compositor is not aware of the
internal state of the client, it may choose to activate the wrong
surface. For this reason, the "activated" event must have a timestamp,
like a user-generated event, which allows the client to activate the
correct surface.

It should be recognized that in the absence of sophisticated
interactions like drag-and-drop a client receiving a button press
event already has been or is about to be activated; the crossing
events preceded button events, so point-to-focus policies activate
earlier than click-to-focus polices would.

Clients can support both point-to-focus policies and click-to-focus
polices by using both crossing events and button events to request
activation. A surface using a button event in addition to a crossing
event will not create a problem for point-to-focus users, because the
surface, compositor permitting, will already be active when the button
event occurs. It will not create a problem for click-to-focus users
because they can instruct the compositor to ignore requests from
crossing events, but this is not without cost because otherwise silent
clients will be chattering with requests which will be denied.
Conversely, clients not using crossing events to request activation
may appear to be non-responsive or slowly responsive to point-to-focus
users. The compositor could force a point-to-focus policy, but would
do so at the cost of the aforementioned sophisticated interactions.

I believe a flag of some sort from the compositor to indicate the
user's preference is a good way to reduce chatter, support both kinds
of policies, and allow for sophistication. I recommend a signed
integer value, perhaps "crossing_activation_timeout", interpreted as
follows:

n = -1: Clients should not expect crossing event activation requests
will be honored.
n >= 0: Clients should expect crossing event activation request to be
honored n milliseconds after the timestamp, if at all.

In the latter case, clients should expect the compositor to handle the
timing and so not delay their requests. I imagine clients may be able
to make use of the timing information, but if that is not so, then a
simple boolean like "crossing_activation_accepted" should suffice.

The compositor should be able to handle deactivation for the
PointerRoot focus policy, if anybody even uses that.

I have neglected to mention pointer warping because I hope nobody does
that anymore.

Post by Rafael Antognolli
Regarding the surface fullscreen, maximized, etc, I added surface states as
enum's, that can be set/unset, and events from the compositor to request that a
given state should be set/unset.
For those states that take parameters, I added separate requests for setting
the parameters before setting the state. It should all take place after commit
anyway, so that shouldn't matter much. Take a look at the docs and say what you
think.
I didn't change transient/popup surface types yet, but from what has been said
in the ML thread, I think they also should be surface states now. Correct me if
I'm wrong. Otherwise I'm going to send an updated version with those changes
tomorrow.
I also talked to jekstrand (I think) about stacking, will send an updated
version with what I understood from that tomorrow. Should be simple.

I have of course assumed that surfaces would not normally be raised in
the absence of activation. I believe stacking can and should be left
to clients within constraints imposed by the compositor except for
those special cases, like window switching, where it makes sense for
the compositor to shuffle windows around.

Because a new surface may remain not activated, I believe compositors
should initially place them beneath the active surface and possible
below all the normal surfaces. (Not below a desktop window, obviously,
for that would forever obscure it.)

Post by Rafael Antognolli
Any feedback is appreciated, and thank you guys for the input so far and the
patience.
xdg_shell: Add a new shell protocol.
protocol/Makefile.am | 2 +-
protocol/xdg-surface.xml | 381 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 382 insertions(+), 1 deletion(-)
create mode 100644 protocol/xdg-surface.xml
--
1.8.3.1
_______________________________________________
wayland-devel mailing list
wayland-devel at lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

One of these days I shall learn brevity.

[Axel Davy]

Hello,

There has been some discussions on IRC about the possible support of
decoration side negociation in xdg_shell.

A client would have to support CSD if it uses xdg_shell.

And I suggested the folowing mechanism:

.when binding to xdg_shell,
the client gets an event telling him the compositors's
preferred mode between CSD and SSD.

. When creating a surface, the client tells which he prefers between
CSD and SSD

. The client gets back an event to tell him what will be the decoration mode
for the surface (the compositor can follow client choice, or enforce CSD
or SSD).

And I suggest too to be able to change that after creation (ie be able to
send a new request to tell to the compositor the client wants to change
of mode,
and the client would get the back the same event than before, telling
him what the compositor wants him to use).


Axel Davy

Post by Rafael Antognolli
Hello all,
Following is the same description as in my previous wrong email, but with the
correct patch attached.
I'm trying to summarize part of the discussion in this new patch, but it's not
the final one.
As far as I understood, the goal is to end up with something like this for
W = compositor
A, Z = client surfaces
W to Z: You are deactivated.
W to A: You are activated.
A to W: Do these things.
So, I added "activated" and "deactivated" events, that the compositor can use
to inform clients what they are. And there's a take_focus request that can be
used by a client to ask for activation, but it's up to the compositor to
decide.
Regarding the surface fullscreen, maximized, etc, I added surface states as
enum's, that can be set/unset, and events from the compositor to request that a
given state should be set/unset.
For those states that take parameters, I added separate requests for setting
the parameters before setting the state. It should all take place after commit
anyway, so that shouldn't matter much. Take a look at the docs and say what you
think.
I didn't change transient/popup surface types yet, but from what has been said
in the ML thread, I think they also should be surface states now. Correct me if
I'm wrong. Otherwise I'm going to send an updated version with those changes
tomorrow.
I also talked to jekstrand (I think) about stacking, will send an updated
version with what I understood from that tomorrow. Should be simple.
Any feedback is appreciated, and thank you guys for the input so far and the
patience.
xdg_shell: Add a new shell protocol.
protocol/Makefile.am | 2 +-
protocol/xdg-surface.xml | 381 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 382 insertions(+), 1 deletion(-)
create mode 100644 protocol/xdg-surface.xml

[Jasper St. Pierre]

And as I explained on IRC, I don't want this in an initial dump. The
motivation of this xdg_shell approach is to keep it small and land it now.
We can add functionality later, but I'd rather not spend too much time in
heated discussions on the list about client-side vs. server-side
decorations.

If you write some code, on the other hand... :)

Post by Axel Davy
Hello,
There has been some discussions on IRC about the possible support of
decoration side negociation in xdg_shell.
A client would have to support CSD if it uses xdg_shell.
.when binding to xdg_shell,
the client gets an event telling him the compositors's
preferred mode between CSD and SSD.
. When creating a surface, the client tells which he prefers between
CSD and SSD
. The client gets back an event to tell him what will be the decoration mode
for the surface (the compositor can follow client choice, or enforce CSD
or SSD).
And I suggest too to be able to change that after creation (ie be able to
send a new request to tell to the compositor the client wants to change of
mode,
and the client would get the back the same event than before, telling
him what the compositor wants him to use).
Axel Davy
Hello all,

Post by Rafael Antognolli
Following is the same description as in my previous wrong email, but with the
correct patch attached.
I'm trying to summarize part of the discussion in this new patch, but it's not
the final one.
As far as I understood, the goal is to end up with something like this for
W = compositor
A, Z = client surfaces
W to Z: You are deactivated.
W to A: You are activated.
A to W: Do these things.
So, I added "activated" and "deactivated" events, that the compositor can use
to inform clients what they are. And there's a take_focus request that can be
used by a client to ask for activation, but it's up to the compositor to
decide.
Regarding the surface fullscreen, maximized, etc, I added surface states as
enum's, that can be set/unset, and events from the compositor to request that a
given state should be set/unset.
For those states that take parameters, I added separate requests for setting
the parameters before setting the state. It should all take place after commit
anyway, so that shouldn't matter much. Take a look at the docs and say what you
think.
I didn't change transient/popup surface types yet, but from what has been said
in the ML thread, I think they also should be surface states now. Correct me if
I'm wrong. Otherwise I'm going to send an updated version with those changes
tomorrow.
I also talked to jekstrand (I think) about stacking, will send an updated
version with what I understood from that tomorrow. Should be simple.
Any feedback is appreciated, and thank you guys for the input so far and the
patience.
xdg_shell: Add a new shell protocol.
protocol/Makefile.am | 2 +-
protocol/xdg-surface.xml | 381 ++++++++++++++++++++++++++++++
+++++++++++++++++
2 files changed, 382 insertions(+), 1 deletion(-)
create mode 100644 protocol/xdg-surface.xml

_______________________________________________
wayland-devel mailing list
wayland-devel at lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel

[Bill Spitzak]

Any proposal must merge in the fullscreen/maximized stuff which is
really an instruction to remove decorations as well.

I see no reason for clients to request whether they "prefer" csd. CSD
will always be better, the only reason to "prefer" ssd is because the
client can't do it, and you already stated that a client that can't draw
it's decorations is not allowed.

However the compositor must be able to tell the client to not add it's
decorations. This is used for:

- fullscreen
- maximized
- snapping against output edges, other windows, or panels
- remote display on a non-wayland system that insists on adding frames
- tabbed or tiled window management.

I propose that the xdg_shell configure request replace the current
"fullscreen" and "maximized" with bitflags, and some of them are:

- Draw the top edge
- Draw the bottom edge
- Draw the right edge
- Draw the left edge
- Draw the titlebar

Possibly these bits should be inverted so that zero is the "normal" case
where things are drawn. "snapping" will probably also require the
compositor to know how thick the edges are, that may have to be sent
from the client as another content rectangle.

Post by Axel Davy
Hello,
There has been some discussions on IRC about the possible support of
decoration side negociation in xdg_shell.
A client would have to support CSD if it uses xdg_shell.