summaryrefslogtreecommitdiffstats
path: root/kdecore/README.kstartupinfo
diff options
context:
space:
mode:
authorTimothy Pearson <kb9vqf@pearsoncomputing.net>2011-11-06 15:56:40 -0600
committerTimothy Pearson <kb9vqf@pearsoncomputing.net>2011-11-06 15:56:40 -0600
commite16866e072f94410321d70daedbcb855ea878cac (patch)
treeee3f52eabde7da1a0e6ca845fb9c2813cf1558cf /kdecore/README.kstartupinfo
parenta58c20c1a7593631a1b50213c805507ebc16adaf (diff)
downloadtdelibs-e16866e072f94410321d70daedbcb855ea878cac.tar.gz
tdelibs-e16866e072f94410321d70daedbcb855ea878cac.zip
Actually move the kde files that were renamed in the last commit
Diffstat (limited to 'kdecore/README.kstartupinfo')
-rw-r--r--kdecore/README.kstartupinfo282
1 files changed, 0 insertions, 282 deletions
diff --git a/kdecore/README.kstartupinfo b/kdecore/README.kstartupinfo
deleted file mode 100644
index cbb6a6dfb..000000000
--- a/kdecore/README.kstartupinfo
+++ /dev/null
@@ -1,282 +0,0 @@
-$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>
-