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

0001 Application startup notification
0002 Lubos Lunak <l.lunak@kde.org>
0003 --------------------------------
0004 --------------------------------
0007  When a new application is started in KDE, together with it a startup
0008 notification is sent, which is used to show a startup entry in taskbar,
0009 the busy icon next to the cursor and put the window of the started app
0010 on correct desktop.
0011  This application startup notification ( ASN for short in the following
0012 text ) usually works fine without problems, but some applications and
0013 some special cases may need special handling.
0014  Right now, this is only an internal KDE standard, but since a toolkit
0015 support would improve the results a bit, I'll try to discuss this
0016 on http://www.freedesktop.org .
0019 Starting apps with ASN :
0020 -------------------------
0022  When an application is started from the K-Menu or the minicli, and from other
0023 places, ASN is sent automatically for it, assuming a matching .desktop file
0024 is found for the starting application. Application without a .desktop file
0025 don't get ASN ( this may change, but it's unlikely as it creates too many
0026 ASNs which will stay too long until a timeout ). For improving the quality
0027 of ASN and reducing the number of ASNs that don't detect when the application
0028 has started, some .desktop file entries may be helpful ( see below ).
0029  If you want to start an application in your code, prefer using KRun or
0030 KApplication::startServiceByXXX() calls. Classes like KProcess don't create
0031 ASN, so if you need to use it, you have to send it manually ( only in case
0032 ASN is useful in this case, it shouldn't be sent e.g. for system processes ).
0035 .desktop files :
0036 -----------------
0038 These following .desktop file entries affect ASN :
0040 X-KDE-StartupNotify=<bool>
0041     - if true, this app/service will get app startup notify
0042     - if false, this app/service will _not_ get app startup notify
0043     - if not set
0044         - if it's service, it will _not_ get app startup notify
0045         - if it's app, it will get app startup notify, but
0046             X-KDE-WMClass will be assumed to be "0" ( non-compliant )
0047 X-KDE-WMClass=<string>
0048     - if set, and it's different from "0" ( without quotes ), this
0049         is the WMClass value for startup notification
0050     - if it's "0" ( without quotes ), such app is considered non-compliant,
0051         and the startup notification will stop
0052             - either if its windows is correctly detected using the default
0053                 WMClass value ( the name of the binary )
0054             - or if a window is mapped that is not recognized ( doesn't have
0055                 neither _KDE_STARTUP_ID nor _NET_WM_PID property /*CHECKME*/),
0056                 it's assumed this window belongs to the started app;
0057                 the start-on-desktop feature won't work then too
0058     - if not set, it defaults to the binary name of the app ( ok for most apps,
0059         including KDE ones )
0060     - to get the WMCLASS value for any app, run 'xprop' and click on the app's
0061         window, WMCLASS value for this app should be any of the strings listed
0062         in the WM_CLASS property ( it's usually the same as the name of the
0063         app's binary file, in such case it doesn't need to be explicitly set )
0064 MapNotify=<bool>
0065     - this key is obsolete
0066     - true is equivalent to X-KDE-StartupNotify=true and no X-KDE-WMClass set
0067     - false is equivalent to X-KDE-StartupNotify=true and X-KDE-WMClass=0
0068         - many .desktop files in KDE ( especially in kdebase/kappfinder )
0069             seem to have MapNotify=false even though it's not needed, this
0070             needs to be checked and replaced by the needed X-KDE-* values,
0071             often just X-KDE-StartupNotify=true should be enough
0073  The best way to check if the entries are set correctly is to start
0074 the application and switch to other desktop. If the startup notification
0075 disappears and the application appears on the desktop on which it was
0076 started, it's correct ( with X-KDE-WMClass=0, the start-on-desktop
0077 feature may not work ).
0079  Ideally, every .desktop file should have X-KDE-StartupNotify set to the correct
0080 value, and for apps which need it also X-KDE-WMClass should be set. This
0081 sometimes gives slightly better behavior than when these entries are not set.
0084 The KStartupInfo classes : 
0085 --------------------------
0087  In some cases, or if you are interested in getting the ASN information, you
0088 have to use the KStartupInfo classes in kdelibs/kdecore.
0090 Receiving the application startup notification information :
0091 ------------------------------------------------------------
0093  Create an instance of class KStartupInfo and connect to its slots, they
0094 will be emitted whenever a ASN info is received.
0095  The clean_on_cantdetect argument to the constructor means whether all
0096 ASN info for non-compliant apps should be removed when a window is mapped
0097 which cannot be identified ( it's not possible to say if it belong to one
0098 of the starting applications or not ). If the argument is true, it is
0099 assumed that the window does belong to one of the starting applications,
0100 and all ASN info for non-compliant apps must be removed, otherwise the ASN
0101 info would timeout ( e.g. kdesktop sets it to true, otherwise the busy
0102 icon would sometimes stay for too long, which is oftern annoying ).
0103 On the other hand, KWin, which maps the first window of the starting apps
0104 to the given virtual desktop, sets it to false, because there's no visual
0105 representation and if a window for a starting non-compliant application is
0106 detected later, it still will be successfully places on the correct virtual
0107 desktop.
0108  Note that the ASN info is often send in several messages, and the slots
0109 will be therefore emitted several times, with the updated info ( e.g. the
0110 binary name or PID is not know from the beginning ).
0112 Sending the application startup notification information :
0113 ----------------------------------------------------------
0115  Before an application is started, ASN info for it must be sent ( unless
0116 it's done by classes like KRun ). See e.g. KRun sources for details.
0117  During the starting of the application, the info may need some updating
0118 ( e.g. right after starting the app, the PID with hostname may be sent,
0119 or a PID change when KUniqueApplication forks into background ).
0120  When it's detected that the started process exited, it an ASN info
0121 about the finished process should be sent. Since the application may
0122 have forked into background, the finish info should include the PID
0123 and hostname, and the notification will be stopped only if there's
0124 no other PID for it. On the other hand, if you simply really need
0125 to stop ASN, send only the identification ( KStartupInfo::sendFinish()
0126 with only KStartupInfoId argument ).
0130 Implementation details :
0131 ------------------------
0133  The ASN info data is sent using X ClientMessages as text ( see below ),
0134 this is mainly in hope also non-KDE people will start using it, and
0135 they wouldn't be very happy with DCOP.
0136  Before starting an application, and environment variable called
0137 KDE_STARTUP_ENV is added to it's environment, and it's set to unique
0138 identifier of its startup notification, or "0" for disabled ASN.
0139 Ideally, the application should read it, and set a window property
0140 called _KDE_STARTUP_ID ( type XA_STRING ) at least on its first mapped
0141 toplevel window to this value. It should also unset it, so it doesn't get
0142 propagated to other applications started from it. It should also
0143 update the ASN info when necessary, e.g. when KUniqueApplication
0144 forks into background, it sends the PID change. That's how compliant
0145 applications should work, and this support for ASN should be provided
0146 by toolkits. All KDE application should be compliant by now, since
0147 kdelibs do all the necessary things. The KDE_STARTUP_ENV variable
0148 is read and unset in KApplication constructor, and _KDE_STARTUP_ID
0149 is set on every toplevel window in KApplication::setTopWidget().
0150  However, majority of applications aren't compliant now, and even
0151 if I succeed making this thing a standard ( part of NETWM_SPEC
0152 or whatever ), there still will be old applications that won't behave
0153 this way. Not unsetting KDE_STARTUP_ENV is not a big problem, since
0154 the ASN for its value will usually timeout, and when the app starts
0155 a new application, this ASN identification value will get reused without
0156 problems. The other problem is detecting, which newly mapped windows
0157 belong to which starting application. If a newly mapped window doesn't
0158 have _KDE_STARTUP_ID property, the code tries to read its _NET_WM_PID
0159 property, and if it's set, it tries to match it ( together with
0160 WM_CLIENT_MACHINE ) with PIDs of all ASN infos. And if the window
0161 doesn't have even the _NET_WM_PID property, WM_CLASS property is used
0162 then. It's usually set to two strings, and at least one of them is
0163 usually the binary name of the application, so it's converted
0164 to lowercase and compared. For applications, where such comparison
0165 would fail, the X-KDE-WMClass .desktop file entry should be set
0166 to the correct WMClass value ( e.g. for XEmacs, the binary name
0167 is 'xemacs', but WM_CLASS is 'emacs', 'Emacs', so its X-KDE-WMClass
0168 in its .desktop file should be set to 'emacs' - the case doesn't
0169 matter ).
0170  The ASN identification string must be a unique string for every ASN.
0171 In KStartupInfo class, it's created as 'hostname;tm.sec;tm.usec;pid',
0172 tm being the current time. If the identification string is set to "0",
0173 it means no ASN should be done ( e.g. for things like kio_uiserver,
0174 which shouldn't get ASN ). Empty identification string means the same
0175 like "0", except for the call to KStartupInfoId::initId(), where it means
0176 to create a new one.
0179 Format of the text messages :
0180 -----------------------------
0182 There are 3 types of messages :
0183  - new: message
0184     - this message announces that a new application is being started,
0185       if there is not ASN info for this ASN identification, it should be
0186       updated, otherwise it will be created
0187     - the text of the message starts with 4 characters 'new:', followed
0188       by the text entries ( see below )
0189  - change: message
0190     - this message is like new: message, but it's only for updating existing
0191       ASN info, if there's no ASN info for the given identification, it won't
0192       be created. This is used e.g. in KUniqueApplication when it forks
0193       into background and sends info about the PID change - it should update
0194       any existing ASN info, but mustn't create a new one, otherwise there
0195       could appear ASN even for applications which shouldn't have ASN
0196     - the text of the message starts with 4 characters 'change:', followed
0197       by the text entries ( see below )
0198  - remove: message
0199     - this message is sent for stopping ASN with the given identification.
0200       If the only item in the message is the identification string, the ASN
0201       info should be removed. If there are also the PID and HOSTNAME entries
0202       ( see below ), the matching ASN info should be only removed if this
0203       given PID is the only PID for it ( in this case, the identification
0204       string may be omitted ).
0205     - the text of the message starts with 4 characters 'remove:', followed
0206       by
0207           - only ID entry
0208           - only ID, PID and HOSTNAME entries
0209           - only PID and HOSTNAME entries
0212 Text entries in the messages :
0213 ------------------------------
0215 Every entry is of the form <name>=<value>. Value may be either a number
0216 or a string. If the string contains spaces, it must be quoted ("), all
0217 backslashes and quotes (") must be escaped by backslashes. If this ever
0218 becomes more than an internal KDE standard, non-standard entry names should
0219 start with an underscore.
0221 Entries :
0223 - ID        - string
0224             - the identification string of the startup notification
0225             - it must be present in all messages except for the remove:
0226               message with only PID and HOSTNAME
0227 - BIN       - string
0228             - the binary name of the starting application
0229             - usually used as a fallback value if WMCLASS is not present
0230             - e.g. 'kcontrol'
0231 - NAME      - string
0232             - the name of the starting application
0233             - usually used only for displaying it when indicating that
0234               the application is starting
0235             - e.g. 'Control Center'
0236 - ICON      - string
0237             - the icon for this startup notification
0238             - it should be handled like the Icon= entry in .desktop files
0239             - e.g. 'kcontrol'
0240 - DESKTOP   - number
0241             - the virtual desktop on which the application should appear
0242             - if the application's first window has _NET_WM_DESKTOP already
0243               set when the window is mapped, it shouldn't be changed
0244 - WMCLASS   - string
0245             - the WMCLASS value used for matching newly mapped windows
0246               of non-compliant applications
0247             - useful only if it's different from the binary
0248               name of the application
0249 - PID       - number
0250             - the PID of a process that belongs to this startup notification
0251             - there may be several PIDs for one notification
0252             - value 0 is also valid, meaning that there's a process
0253               with unknown PID for this notification ( is used e.g.
0254               by kfmclient when it sends a DCOP message to already running
0255               konqueror instance to create a new window and exits immediately,
0256               without adding the zero PID to the notification, process
0257               that started kfmclient could detect it exited and would send
0258               a remove: message for the notification with kfmclient's PID,
0259               which would cause the notification to stop if there wasn't also
0260               PID=0 for it
0261 - HOSTNAME  - string
0262             - the hostname of the machine on which the application is being
0263               started
0264             - this is used together with the PID entry
0266 --------------------
0268  Well, I guess that's all. The KDE2.2 release will show if the users like it
0269 or not ( it's quite good IMHO, even though there are probably some minor
0270 details to fix or improve ). The only big thing remaining is to make also
0271 non-KDE people agree on using something like this. My first attempt
0272 https://listman.redhat.com/pipermail/xdg-list/2001-May/000083.html
0273 didn't get much attention, but now that there's a working implementation,
0274 I hope it will get better, when I try again sometime in the future.
0278  Lubos Lunak <l.lunak@kde.org>