Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 282 insertions, 0 deletions

diff --git a/kdecore/README.kstartupinfo b/kdecore/README.kstartupinfo
new file mode 100644
index 000000000..233ccde1e
--- /dev/null
+++ b/kdecore/README.kstartupinfo
@@ -0,0 +1,282 @@
+$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/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>
+