Hello. On March 10 I sent an email to the original authors of the tray icon specification (Havoc and Mark) proposing some changes to the spec. I received no reply.
Matthias Clasen was also cc:'d on the email and we discussed the
proposed changes. Matthias is in agreement with my proposal.
These changes are required to deal with shortcomings in the
specification caused by some assumptions that are no longer valid.
I've attached a diff to the spec that I'd like to be able to upload.
I'm also including the original mail here for an overview of why these
changes are required.
Cheers
---original mail follows---
Hello.
I'm writing about releasing an update (0.3) to the current
freedesktop.org tray icon specification.
The current tray icon specification has two problems that I would like
to see addressed. I'm willing to make the changes and publish the new
version if someone explains the process to me.
I'm also willing to update GtkStatusIcon to comply to the new
conventions outlined here, assuming the changes are accepted to the
specification.
The two changes that I feel are required:
1) The current "orientation" hint is broken.
It is set on the manager window despite the fact that individual tray
icons can, in theory, be located in different places. This includes the
possibility that some tray icons are located on panels with horizontal
orientation and others on panels with vertical orientation.
As a solution to this problem I propose that the tray manager sets a
property on the docking child window specifying which orientation it
should have. The fallback behaviour would be that clients fall back to
looking at the property set on the manager window.
Specifically:
A client decides its orientation by doing the following:
1) check if someone has set the orientation property on its window
2) if no such orientation is set, look at the manager window.
A server notifies of orientation by doing:
1) set the orientation property on the client window
2) if all icons have the same orientation, set the property on manager
-- if orientation is different for some icons then (???)
We might also want to consider adding an "undocked" orientation. I have
no immediate plans for this but it seems like it might be useful....
2) Visual matching is a problem.
Currently, GtkStatusIcon sets a ParentRelative background pixmap on
itself to indicate that it should obtain its background image from its
parent. This only works if the parent window and the child window have
the same visual. It's also a giant hack.
In the current case, if you dock a normal GtkStatusIcon (RGB,
ParentRelative) into a RGBA panel then you get a BadMatch error and the
docking fails. Fortunately, GtkSocket has X error traps in it, so it
doesn't crash outright.
The real problem, of course, is that the tray icon client currently has
no way of determining the visual of the parent that it is requesting
docking into. My suggestion is that we use the following convention:
a) The server-side sets the visual of the invisible manager window to
the visual that it wants the children to use for creating their windows.
b) The client inspects the visual of the manager window before creating
its X window and creates the window with this visual.
c) If the server receives a dock request and discovers that the child
window (which it has the XID of as part of the dock request) has the
incorrect visual then it mitigates this problem by destroying and
rerealizing its socket to receive the child into using the correct
visual. This is fallback behaviour to support clients that don't yet
follow the convention outlined here.
d) If the client sees that the visual of the manager is an RGBA visual
then it turns off all hacks regarding ParentRelative backgrounds and
instead uses a real alpha transparent background for itself.
Feedback on these ideas is appreciated -- including how I can get them
into the spec.
Cheers
Index: systemtray-spec.xml
===================================================================
RCS file: /cvs/systemtray/systemtray-spec/systemtray-spec.xml,v
retrieving revision 1.2
diff -u -r1.2 systemtray-spec.xml
--- systemtray-spec.xml 30 Nov 2004 09:34:17 -0000 1.2
+++ systemtray-spec.xml 18 Mar 2007 04:40:49 -0000
@@ -187,12 +187,30 @@
widget embedding.
</para>
<para>
- To begin the docking process, the tray icon application sends
+ A tray icon should create its "client" window with the same visual
+ and colourmap as the manager window. If the visual is an RGB visual
+ then the client may choose to implement transparency through the use
+ of a ParentRelative background. If the visual is an RGBA visual
+ then the client can assume that compositing is supported by the
+ manager and should draw alpha transparency for its background.
+ </para>
+ <para>
+ To begin the actual docking process, the tray icon application sends
a client message event to the manager selection owner window,
as described in <xref linkend="messages"/>. This event
should contain the <literal>SYSTEM_TRAY_REQUEST_DOCK</literal>
opcode, <literal>xclient.data.l[2]</literal> should contain
- the X window ID of the tray icon to be docked.
+ the X window ID of the tray icon (created as per the last paragraph).
+ </para>
+ <para>
+ When the manager receives a dock request it should examine the
+ visual and colourmap of the window given in the request. Before
+ starting the XEMBED process, the manager must ensure that the
+ immediate future parent of the window (ie: the "socket") has the
+ same visual as the icon to be docked. This check must be performed
+ since clients written to an earlier version of this specificiation
+ may fail to properly match the visual of their window with that of
+ the manager window.
</para>
<para>
At this point the "embedding life cycle" explained in the XEMBED
@@ -253,7 +271,37 @@
of the icon data.
</para>
</sect2>
+ <sect2>
+ <title>_NET_SYSTEM_TRAY_ORIENTATION</title>
+ <programlisting><![CDATA[
+_NET_SYSTEM_TRAY_ORIENTATION orientation CARDINAL/32
+]]>
+ #define _NET_SYSTEM_TRAY_ORIENTATION_HORZ 0
+ #define _NET_SYSTEM_TRAY_ORIENTATION_VERT 1
+ </programlisting>
+
+ <para>
+ The property should be set by the tray manager to indicate the
+ current orientation of the tray in which this icon is located.
+ This is used by tray managers that support locating individual
+ tray icons in different orientations.
+ </para>
+
+ <para>
+ If this property is not set then the tray icon must fall back
+ to checking the global orientation property set on the manager
+ window. As such, a tray manager that requires all icons to be
+ located in the same orientation may choose not to set this
+ property.
+ </para>
+ <para>
+ If this property is to be set then the tray manager should ensure
+ that it is set to its initial value before initiating the XEMBED
+ process.
+ </para>
+
+ </sect2>
</sect1>
<sect1 id="manager-hints">
@@ -273,10 +321,20 @@
</programlisting>
<para>
-The property should be set by the tray manager to indicate the current
-orientation of the tray. Tray icons may use this hint in order to
-maintain the icon's aspect ratio and also as an indication of how the
-icon contents should be laid out.
+ This property should be set by the tray manager to indicate the
+ current orientation of the tray. This property is a fallback
+ for when a per-icon property hasn't been set on the icon window.
+ </para>
+
+ <para>
+ Manager implementations which support the per-icon orientation
+ should still set this property for compatibility with clients
+ written to an older version of this specification. If it is
+ not possible to correctly set this property (for example, due
+ to the possibility of some icons having different orientation
+ than others) then the choice of what to set this property to
+ (or if to set it at all) is left to the descretion of the
+ implementor.
</para>
</sect2>
@@ -353,6 +411,24 @@
<appendix id="changes">
<title>Change history</title>
<formalpara>
+ <title>Version 0.3, 18 March 2007, Ryan Lortie</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Added the per-icon _NET_SYSTEM_TRAY_ORIENTATION hint.
+ </para>
+ <para>
+ Added requirements for visual matching (on both sides)
+ and specified the behaviour for icons which wish to be
+ transparent.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara>
<title>Version 0.2, 23 November 2004, Mark McLoughlin</title>
<para>
<itemizedlist>
@@ -364,6 +440,7 @@
</itemizedlist>
</para>
</formalpara>
+
<formalpara>
<title>Version 0.1, 20 April 2002, Havoc Pennington</title>
<para>
signature.asc
Description: This is a digitally signed message part
_______________________________________________ xdg mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/xdg
