tdelibs/tdecore/README.kstartupinfo

$Id$


Application startup notification
Lubos Lunak <l.lunak@kde.org>
--------------------------------
--------------------------------


 When a new application is started in KDE, together with it a startup
notification is sent, which is used to show a startup entry in taskbar,
the busy icon next to the cursor and put the window of the started app
on correct desktop.
 This application startup notification ( ASN for short in the following
text ) usually works fine without problems, but some applications and
some special cases may need special handling.
 Right now, this is only an internal KDE standard, but since a toolkit
support would improve the results a bit, I'll try to discuss this
on http://www.freedesktop.org .


Starting apps with ASN :
-------------------------

 When an application is started from the K-Menu or the minicli, and from other
places, ASN is sent automatically for it, assuming a matching .desktop file
is found for the starting application. Application without a .desktop file
don't get ASN ( this may change, but it's unlikely as it creates too many
ASNs which will stay too long until a timeout ). For improving the quality
of ASN and reducing the number of ASNs that don't detect when the application
has started, some .desktop file entries may be helpful ( see below ).
 If you want to start an application in your code, prefer using KRun or
KApplication::startServiceByXXX() calls. Classes like KProcess don't create
ASN, so if you need to use it, you have to send it manually ( only in case
ASN is useful in this case, it shouldn't be sent e.g. for system processes ).
 

.desktop files :
-----------------

These following .desktop file entries affect ASN :

X-KDE-StartupNotify=<bool>
    - if true, this app/service will get app startup notify
    - if false, this app/service will _not_ get app startup notify
    - if not set
        - if it's service, it will _not_ get app startup notify
        - if it's app, it will get app startup notify, but
            X-KDE-WMClass will be assumed to be "0" ( non-compliant )
X-KDE-WMClass=<string>
    - if set, and it's different from "0" ( without quotes ), this
        is the WMClass value for startup notification
    - if it's "0" ( without quotes ), such app is considered non-compliant,
        and the startup notification will stop
            - either if its windows is correctly detected using the default
                WMClass value ( the name of the binary )
            - or if a window is mapped that is not recognized ( doesn't have
                neither _KDE_STARTUP_ID nor _NET_WM_PID property /*CHECKME*/),
                it's assumed this window belongs to the started app;
                the start-on-desktop feature won't work then too
    - if not set, it defaults to the binary name of the app ( ok for most apps,
        including KDE ones )
    - to get the WMCLASS value for any app, run 'xprop' and click on the app's
        window, WMCLASS value for this app should be any of the strings listed
        in the WM_CLASS property ( it's usually the same as the name of the
        app's binary file, in such case it doesn't need to be explicitly set )
MapNotify=<bool>
    - this key is obsolete
    - true is equivalent to X-KDE-StartupNotify=true and no X-KDE-WMClass set
    - false is equivalent to X-KDE-StartupNotify=true and X-KDE-WMClass=0
        - many .desktop files in KDE ( especially in kdebase/kappfinder )
            seem to have MapNotify=false even though it's not needed, this
            needs to be checked and replaced by the needed X-KDE-* values,
            often just X-KDE-StartupNotify=true should be enough
        
 The best way to check if the entries are set correctly is to start
the application and switch to other desktop. If the startup notification
disappears and the application appears on the desktop on which it was
started, it's correct ( with X-KDE-WMClass=0, the start-on-desktop
feature may not work ).

 Ideally, every .desktop file should have X-KDE-StartupNotify set to the correct
value, and for apps which need it also X-KDE-WMClass should be set. This
sometimes gives slightly better behavior than when these entries are not set.


The KStartupInfo classes : 
--------------------------

 In some cases, or if you are interested in getting the ASN information, you
have to use the KStartupInfo classes in kdelibs/tdecore.

Receiving the application startup notification information :
------------------------------------------------------------

 Create an instance of class KStartupInfo and connect to its slots, they
will be emitted whenever a ASN info is received.
 The clean_on_cantdetect argument to the constructor means whether all
ASN info for non-compliant apps should be removed when a window is mapped
which cannot be identified ( it's not possible to say if it belong to one
of the starting applications or not ). If the argument is true, it is
assumed that the window does belong to one of the starting applications,
and all ASN info for non-compliant apps must be removed, otherwise the ASN
info would timeout ( e.g. kdesktop sets it to true, otherwise the busy
icon would sometimes stay for too long, which is oftern annoying ).
On the other hand, KWin, which maps the first window of the starting apps
to the given virtual desktop, sets it to false, because there's no visual
representation and if a window for a starting non-compliant application is
detected later, it still will be successfully places on the correct virtual
desktop.
 Note that the ASN info is often send in several messages, and the slots
will be therefore emitted several times, with the updated info ( e.g. the
binary name or PID is not know from the beginning ).

Sending the application startup notification information :
----------------------------------------------------------

 Before an application is started, ASN info for it must be sent ( unless
it's done by classes like KRun ). See e.g. KRun sources for details.
 During the starting of the application, the info may need some updating
( e.g. right after starting the app, the PID with hostname may be sent,
or a PID change when KUniqueApplication forks into background ).
 When it's detected that the started process exited, it an ASN info
about the finished process should be sent. Since the application may
have forked into background, the finish info should include the PID
and hostname, and the notification will be stopped only if there's
no other PID for it. On the other hand, if you simply really need
to stop ASN, send only the identification ( KStartupInfo::sendFinish()
with only KStartupInfoId argument ).



Implementation details :
------------------------

 The ASN info data is sent using X ClientMessages as text ( see below ),
this is mainly in hope also non-KDE people will start using it, and
they wouldn't be very happy with DCOP.
 Before starting an application, and environment variable called
KDE_STARTUP_ENV is added to it's environment, and it's set to unique
identifier of its startup notification, or "0" for disabled ASN.
Ideally, the application should read it, and set a window property
called _KDE_STARTUP_ID ( type XA_STRING ) at least on its first mapped
toplevel window to this value. It should also unset it, so it doesn't get
propagated to other applications started from it. It should also
update the ASN info when necessary, e.g. when KUniqueApplication
forks into background, it sends the PID change. That's how compliant
applications should work, and this support for ASN should be provided
by toolkits. All KDE application should be compliant by now, since
kdelibs do all the necessary things. The KDE_STARTUP_ENV variable
is read and unset in KApplication constructor, and _KDE_STARTUP_ID
is set on every toplevel window in KApplication::setTopWidget().
 However, majority of applications aren't compliant now, and even
if I succeed making this thing a standard ( part of NETWM_SPEC
or whatever ), there still will be old applications that won't behave
this way. Not unsetting KDE_STARTUP_ENV is not a big problem, since
the ASN for its value will usually timeout, and when the app starts
a new application, this ASN identification value will get reused without
problems. The other problem is detecting, which newly mapped windows
belong to which starting application. If a newly mapped window doesn't
have _KDE_STARTUP_ID property, the code tries to read its _NET_WM_PID
property, and if it's set, it tries to match it ( together with
WM_CLIENT_MACHINE ) with PIDs of all ASN infos. And if the window
doesn't have even the _NET_WM_PID property, WM_CLASS property is used
then. It's usually set to two strings, and at least one of them is
usually the binary name of the application, so it's converted
to lowercase and compared. For applications, where such comparison
would fail, the X-KDE-WMClass .desktop file entry should be set
to the correct WMClass value ( e.g. for XEmacs, the binary name
is 'xemacs', but WM_CLASS is 'emacs', 'Emacs', so its X-KDE-WMClass
in its .desktop file should be set to 'emacs' - the case doesn't
matter ).
 The ASN identification string must be a unique string for every ASN.
In KStartupInfo class, it's created as 'hostname;tm.sec;tm.usec;pid',
tm being the current time. If the identification string is set to "0",
it means no ASN should be done ( e.g. for things like kio_uiserver,
which shouldn't get ASN ). Empty identification string means the same
like "0", except for the call to KStartupInfoId::initId(), where it means
to create a new one.


Format of the text messages :
-----------------------------

There are 3 types of messages :
 - new: message
    - this message announces that a new application is being started,
      if there is not ASN info for this ASN identification, it should be
      updated, otherwise it will be created
    - the text of the message starts with 4 characters 'new:', followed
      by the text entries ( see below )
 - change: message
    - this message is like new: message, but it's only for updating existing
      ASN info, if there's no ASN info for the given identification, it won't
      be created. This is used e.g. in KUniqueApplication when it forks
      into background and sends info about the PID change - it should update
      any existing ASN info, but mustn't create a new one, otherwise there
      could appear ASN even for applications which shouldn't have ASN
    - the text of the message starts with 4 characters 'change:', followed
      by the text entries ( see below )
 - remove: message
    - this message is sent for stopping ASN with the given identification.
      If the only item in the message is the identification string, the ASN
      info should be removed. If there are also the PID and HOSTNAME entries
      ( see below ), the matching ASN info should be only removed if this
      given PID is the only PID for it ( in this case, the identification
      string may be omitted ).
    - the text of the message starts with 4 characters 'remove:', followed
      by
          - only ID entry
	  - only ID, PID and HOSTNAME entries
	  - only PID and HOSTNAME entries


Text entries in the messages :
------------------------------

Every entry is of the form <name>=<value>. Value may be either a number
or a string. If the string contains spaces, it must be quoted ("), all
backslashes and quotes (") must be escaped by backslashes. If this ever
becomes more than an internal KDE standard, non-standard entry names should
start with an underscore.

Entries :

- ID        - string
            - the identification string of the startup notification
            - it must be present in all messages except for the remove:
              message with only PID and HOSTNAME
- BIN       - string
            - the binary name of the starting application
            - usually used as a fallback value if WMCLASS is not present
            - e.g. 'kcontrol'
- NAME      - string
            - the name of the starting application
            - usually used only for displaying it when indicating that
              the application is starting
            - e.g. 'Control Center'
- ICON      - string
            - the icon for this startup notification
            - it should be handled like the Icon= entry in .desktop files
            - e.g. 'kcontrol'
- DESKTOP   - number
            - the virtual desktop on which the application should appear
            - if the application's first window has _NET_WM_DESKTOP already
              set when the window is mapped, it shouldn't be changed
- WMCLASS   - string
            - the WMCLASS value used for matching newly mapped windows
              of non-compliant applications
            - useful only if it's different from the binary
              name of the application
- PID       - number
            - the PID of a process that belongs to this startup notification
            - there may be several PIDs for one notification
            - value 0 is also valid, meaning that there's a process
              with unknown PID for this notification ( is used e.g.
              by kfmclient when it sends a DCOP message to already running
              konqueror instance to create a new window and exits immediately,
              without adding the zero PID to the notification, process
              that started kfmclient could detect it exited and would send
              a remove: message for the notification with kfmclient's PID,
              which would cause the notification to stop if there wasn't also
              PID=0 for it
- HOSTNAME  - string
            - the hostname of the machine on which the application is being
              started
            - this is used together with the PID entry

--------------------

 Well, I guess that's all. The KDE2.2 release will show if the users like it
or not ( it's quite good IMHO, even though there are probably some minor
details to fix or improve ). The only big thing remaining is to make also
non-KDE people agree on using something like this. My first attempt
https://listman.redhat.com/pipermail/xdg-list/2001-May/000083.html
didn't get much attention, but now that there's a working implementation,
I hope it will get better, when I try again sometime in the future.



 Lubos Lunak <l.lunak@kde.org>