Re: Status Manager

[Gregory Merchan <merchan phys lsu edu>]

Scroll down about 60 lines for the good stuff. :-)

On Sun, Mar 24, 2002 at 03:21:29PM -0500, Havoc Pennington wrote:
>  - small tweaks to the existing protocol are far easier to get going
>    across both gnome/kde, both politically and technically

With regard to the politics . . . get over it. No lives are at stake here.

Fixing GNOME is easy; I've already written most of the needed code.
Fixing KDE is a little bit harder. But after looking at the code
for the last 24 hrs., I could probably do it - and I don't know C++.


>  - your documentation of your proposal is very limited, I do not
>    personally understand how it all works.

It is brief because it is simple. The details are in the ICCCM.


>  - we are just taking your word for "works occasionally," clearly
>    someone thinks it works, I don't have any reason to believe you
>    vs. them.

The KDE protocol depends on the window manager. When the window manager
does not comply, it does not work. All you have to believe is your eyes.


> I'm not "stonewalling" - I'm trying to understand all the issues.

You are stonewalling. If you were instead trying to understand all the
issues you would be asking questions more than you are pushing to
get the broken protocol adopted.


> Because I know a clear explanation of the issues (and better docs on
> the ongoing proposal) are going to be required here. And the burden of
> proof is on any attempt to modify existing practice, so we need to
> have a clear analysis of what's wrong with existing practice if
> anything, not just your opinion. This means starting with what the
> existing practice _is_. Until then I don't have an opinion on it and
> neither should anyone else.

Suppose the existing practice has ten steps and only the first three
are documented. If the second step is broken, there's no need to know
the undocumented remaining seven steps. Such is the case here.
You don't need to check the pulse of a decapitated man.


Nonetheless, here is a recapitulation of existing practice and the proposal.
The sources for existing practice are KDE docs and code sources (some listed)
and GNOME panel code sources. Each description states what the application
providing a tray window (docklet), window manager, and system tray are
responsible for.

KDE Protocol
------------
Application:
  Initialization:
    Create a window.
    Set a property on it:
      Property: _KDE_NET_SYSTEM_TRAY_WINDOW_FOR
      Type:     WINDOW
      Format:   32
      Data:     any, possibly an application window which is represented.
    Map the window.
  Shutdown:
    Unmap or Destroy the window
(Source: http://developer.kde.org/documentation/kde2arch/protocols-docking.html)

Window Manager:
  Initialization:
    Add to _NET_SUPPORTED atom list:
      _KDE_NET_SYSTEM_TRAY_WINDOW_FOR
      _KDE_NET_SYSTEM_TRAY_WINDOWS
  When MapRequest of window with property _KDE_NET_WM_SYSTEM_TRAY_WINDOW_FOR:
    SelectInput with StructureNotifyMask.
    Add to save set.
    Append window to root property:
      Property: _KDE_NET_SYSTEM_TRAY_WINDOWS
      Type:     WINDOW
      Format:   32
      Data:     id of window
(Sources: kdebase/kwin/workspace.cpp,
          kdelibs/kdecore/netwm.cpp)

System Tray:
  Initialization: [*]
    Reparent windows listed in _KDE_NET_SYSTEM_TRAY_WINDOWS.
  When PropertyNotify on root property _KDE_NET_SYSTEM_TRAY_WINDOWS:
    Reparent new windows in property.
    Remove windows not in property.
(Sources: kdebase/kicker/applets/systemtray/systemtrayapplet.cpp,
          kdelibs/kdecore/kwinmodule.cpp,
          kdelibs/kdecore/netwm.cpp)

[*] I found nothing in the sources that would indicate uniqueness of the
    status dock.

GNOME Protocol (excluding CORBA methods)
----------------------------------------
Application:
  Initialization:
    Create a window
    Set a property on it:
      Property: KDE_DOCKWINDOW
      Type:     KDE_DOCKWINDOW
      Format:   32
      Data:     ? (Not checked)
    Map the window.
  Shutdown:
    Unmap or Destroy the window
Window Manager:
  No interaction specified.

System Tray: (called Status Dock)
  Initialization:
    Create a window.
    Set a property on the window:
      Property: KWM_MODULE
      Type:     KWM_MODULE
      Format:   32
      Data:     2
    Send ClientMessage to Root:
      Mask:    SubstructureNotifyMask
      Format:  32
      Type:    KWM_MODULE
      Data[0]: the window id
  When ClientMessage: [*]
    If type is KWM_MODULE_DOCKWIN_ADD
      Add window id given by xclient.data.l[0]
    If type is KWM_MODULE_DOCKWIN_REMOVE
      Remove window id given by xclient.data.l[0]

[*] I can find nothing in the GNOME sources that would generate either
    of these client messages. The 1.4 version would try to add a window
    with the KDE_DOCKWINDOW property if it appeared on the client list
    property of the root window. The code appears to have been removed
    during porting. However, trying to swallow a window (with the swallower
    applet) iterates over the client list and checks for docklets.


Proposed Protocol
-----------------
Application:
  Initialization:
    Create a window.
    Set a property on any client window:
      Property: any
      Type:     WINDOW
      Format:   32
      Data:     id of the created window.
    ConvertSelection:
      Selection: _NET_STATUS_MANAGER
      Target:    INSERT_PROPERTY
      Property:  the property set
  Shutdown:
    Destroy the created window

Window Manager:
  Not involved.

SystemTray:
  Initialization:
    Manage the _NET_STATUS_MANAGER selection.
  When SelectionRequest for target INSERT_PROPERTY:
    Get the requestor property named in the request.
    Reparent the window specified in the property.
    Map that window.

Further notes and possible extensions on the proposed protocol:

  * That the system tray should be unique is the first indication that a
    selection manager should be used.

  * When the selection conversion with target INSERT_PROPERTY fails,
    either there is no system tray, or the system tray is somehow not
    working. GetSelectionOwner and conversion for other targets, usually
    TIMESTAMP and TARGETS, can provide more information; e.g., target 
    VERSION can be used to check that the protocols are the same version.
    In any case, instantiation of new system tray can be detected by the
    ClientMessage to the root window which is required of selection mangers.

  * It currently stipulates that the docked window is undocked by destruction.
    This is surely the most common case, but there are two other ways:
      1) Unmap the window.
      2) Use ConvertSelection:
           Selection: _NET_STATUS_MANAGER
           Target:    DELETE
           Property:  any property identifying the window to undock:
                      Type: WINDOW
                      Format: 32
                      Data: the id to undock
         The tray would then:
           Unmap the window.
           Reparent it to the root window.

  * The same data window managers provide in the EWMH spec could be provided
    by the tray through other selection targets. The _NET_SUPPORTED target,
    however, is not necessary as the TARGETS target provides the same
    information. (In the same way it's not needed for window mangers which
    are ICCCM 2.0 compliant.)

  * Embedded windows can use window manager hints. The principle difference
    between windows embedded in the tray and applets could be simply the type
    identified.

  * A system tray, panels, et al. are all effectively window managers for
    non-root windows. The principle difference is that mapping on the root
    only requires calling for MapWindow, but mapping in one of the others
    requires another, non-conflicting, means. The selection manager method
    is ideal for this as it is already the preferred method for window
    manager communication in ICCCM 2.0.


Cheers,
Gregory Merchan