From f4e9ec6962aa9c78615db9f37c35ca4610026f7e Mon Sep 17 00:00:00 2001
From: Jon Gjengset <jon@thesquareplanet.com>
Date: Thu, 5 Sep 2013 20:40:11 +0100
Subject: Write README

---
 README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 85 insertions(+), 3 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 2c2efb5..e3728cf 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,86 @@
-mktrayicon
-==========
+# mktrayicon
 
-C wrapper for simply creating system tray icons
+`mktrayicon` is a simple proxy program that lets you create and modify system
+tray icons without having to deal with a graphical toolkit like GTK.
+
+`mktrayicon` expects to be given a name pipe (FIFO) file path when it is
+started, and you control your status icon by writing to this named pipe. *Note
+that the pipe should already be created before you call `mktrayicon`*.
+
+Every line written to the pipe should contain a single letter specifying what
+operation to perform, optionally followed by a space and a parameter to the
+command. Each command should be terminated by a newline. The following commands
+are supported:
+
+  - `q`: Terminate `mktrayicon` and remove the tray icon
+  - `i <icon>`: Set the graphic to use for the tray icon (see `/usr/share/icons`)
+  - `t <text>`: Set the text to display in the icon tooltip
+  - `t`: Remove the icon tooltip
+  - `c <cmnd>`: Set the command to be execute when the user clicks the icon (`cmnd` is passed to `/bin/sh -c`)
+  - `c`: Remove the click handler
+  - `h`: Hide the tray icon
+  - `s`: Show the tray icon
+
+By default, the `none` tooltip icon is used. To change this, pass `-i
+<icon_name>` when running `mktrayicon`.
+
+Note that any script communicating with `mktrayicon` **must**, for the time
+being, send `q` when they are done. Just removing the FIFO file will **not**
+cause the tray icon to be removed.
+
+## Example run
+
+```shell
+#!/bin/bash
+
+# Set up tray icon
+mkfifo /tmp/$$.icon
+./mktrayicon /tmp/$$.icon &
+
+# Manipulate tray icon
+
+# Click handling
+echo "c xterm -e /bin/sh -c 'iwconfig; read'" > /tmp/$$.icon
+
+# Change the icon and tooltip
+for i in none weak ok good excellent; do
+  echo "i network-wireless-signal-$i-symbolic" > /tmp/$$.icon
+  echo "t Signal strength: $i" > /tmp/$$.icon
+  sleep 2
+done
+
+# Remove tooltip and click handler
+echo "c" > /tmp/$$.icon
+echo "t" > /tmp/$$.icon
+
+# Toggle the visibility of the icon for a bit
+for i in {1..3}; do
+  for j in h s; do
+    echo $j > /tmp/$$.icon
+    sleep 1
+  done
+done
+
+# Remove tray icon
+echo "q" > /tmp/$$.icon
+rm /tmp/$$.icon
+```
+
+## Known bugs
+
+This is my first time using the GTK+ C library, and I've got to say it is less
+than pleasant to work with. My biggest issue has been trying to do blocking IO
+without blocking the GUI thread, as GTK seems to not like that. They've
+deprecated most of the threading stuff, and only left this
+`g_main_context_invoke` mess, which doesn't even seem to work all of the time.
+
+So, every now and again, the program will just die completely with the message:
+
+```
+[xcb] Unknown sequence number while processing queue
+[xcb] Most likely this is a multi-threaded client and XInitThreads has not been called
+[xcb] Aborting, sorry about that.
+mktrayicon: xcb_io.c:274: poll_for_event: Assertion `!xcb_xlib_threads_sequence_lost' failed.
+```
+
+If someone has a genious way to fix this, patches are welcome.
-- 
cgit