Warning, /frameworks/kwindowsystem/docs/README.kstartupinfo is written in an unsupported language. File is not indexed.

 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/kdecore.
 
 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>