From 9a43cc0df70a09980e910e6128bba47cdde88484 Mon Sep 17 00:00:00 2001
From: "Serge A. Zaitsev" <zaitsev.serge@gmail.com>
Date: Mon, 9 Jan 2017 16:24:12 +0200
Subject: [PATCH] added readme

---
 README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..38d5a70
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+Tray
+----
+
+Cross-platform, super tiny C99 implementation of a system tray icon with a popup menu.
+
+Works well on:
+
+* Linux/Gtk (libappindicator)
+* Windows XP or newer (shellapi.h)
+* MacOS (Cocoa/AppKit)
+
+There is also a stub implementation that returns errors on attempt to create a tray menu.
+
+# Example
+
+```c
+struct tray tray = {
+    .icon = "icon.png",
+    .menu = (struct tray_menu[]){{"Toggle me", 0, 0, toggle_cb, NULL},
+                                 {"-", 0, 0, NULL, NULL},
+                                 {"Quit", 0, 0, quit_cb, NULL},
+                                 {NULL, 0, 0, NULL, NULL}},
+};
+
+void toggle_cb(struct tray_menu *item) {
+	item->checked = !item->checked;
+	tray_update(&tray);
+}
+
+void quit_cb(struct tray_menu *item) {
+  tray_exit();
+}
+
+...
+
+tray_init(&tray);
+while (tray_loop(1) == 0);
+tray_exit();
+
+```
+
+# API
+
+Tray structure defines an icon and a menu.
+Menu is a NULL-terminated array of items.
+Menu item defines menu text, menu checked and disabled (grayed) flags and a
+callback with some optional context pointer.
+
+```c
+struct tray {
+  char *icon;
+  struct tray_menu *menu;
+};
+
+struct tray_menu {
+  char *text;
+  int disabled;
+  int checked;
+
+  void (*cb)(struct tray_menu *);
+  void *context;
+};
+```
+
+* `int tray_init(struct tray *)` - creates tray icon. Returns -1 if tray icon/menu can't be created.
+* `void tray_update(struct tray *)` - updates tray icon and menu.
+* `int tray_loop(int blocking)` - runs one iteration of the UI loop. Returns -1 if `tray_exit()` has been called.
+* `void tray_exit()` - terminates UI loop.
+
+All functions are meant to be called from the UI thread only.
+
+## Roadmap
+
+[x] Cross-platform tray icon
+[x] Cross-platform tray popup menu
+[x] Separators in the menu
+[x] Disabled/enabled menu items
+[x] Checked/unchecked menu items
+[ ] Nested menus
+[ ] Icons for menu items
+[ ] Rewrite ObjC code in C using ObjC Runtime (now ObjC code breaks many linters and static analyzers)
+[ ] Call GTK code using dlopen/dlsym (to make binaries run safely if Gtk libraries are not available)
+
+## License
+
+This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php),
+ so feel free to integrate it in your commercial products.
+