Initial import

1 files changed, 63 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..4bcc452
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,63 @@
+Words of wisdom
+
+1. Make sure all changed work on both KDE and Gnome
+
+2. The System tray protocol specification can be found at
+	http://freedesktop.org/Standards/systemtray-spec/systemtray-spec-0.1.html
+
+3. The KDE System tray Docking Protocol can be found at
+	http://developer.kde.org/documentation/library/kdeqt/kde3arch/protocols-docking.html
+
+4. The site i use for Xlib reference
+	http://tronche.com/gui/x/xlib/function-index.html
+
+5. Qt Documentation at http://doc.trolltech.com
+
+6. There's do or no do. There's no try.
+
+KDocker Window Docking Strategy and a little bit of history
+-----------------------------------------------------------
+Couple of things that will help you if you are looking through the code.
+I wanted a single instance of KDocker to be running all the time. So,
+whenever a new instance of KDocker was created it would ask the previous
+instance take over.
+
+Two things to know about
+1. Mapping from the PID (process id) to WID (window id)
+2. How to let the previous instance know about app_to_launch
+
+Lets deal with them one by one.
+1. PID to WID mapping is easy if people followed rules. Just read _NET_WM_PID
+for a window. If it matches the one app's PID we just created, that window is
+the one we want to dock. Its not as simple as that. Programs have "splash"
+screens. A nice thing is that these "splash" screen have the _WM_TRANSIENT_FOR
+property set. So, we can skip those windows. There are these bunch of programs
+(like gaim, xmms) that create windows and dont put this property on them. Arrgh.
+What we do to counter these applications is to look for interesting windows
+possibly created by the process until the process dies. Have a look at the code
+for a better understanding.
+
+2. Sending ClientMessages to previous instances with the program name and
+arguments is painful and makes the code more complex. Before 1.0, I used to dump
+all the program arguments in ~/kdocker.<pid> and send the pid in a 
+ClientMessage. The file is then deleted after processing. As of 1.0, I set a
+property _KDOCKER_<pid> on the KDocker initial instance's window which holds
+the program arguments. (The correct way to transfer information is using
+XSelections)
+
+TRACING
+-------
+Add the following line in kdocker.pro (in fact just uncomment it)
+DEFINES += ENABLE_TRACING
+
+Now do a "make clean" and "then make".
+
+Launch KDocker. Try recreating the problem.
+- Right Click on the tray icon.
+- Choose "About KDocker"
+- You should see a button called "Show Trace". Please note that this button
+  will appear only when compiled with tracing
+- Try debugging yourself or send it to me
+- If you send SIGUSR1 to the KDocker process, it will dump all the trace to
+  ~/kdocker.trace
+