Sync README with current public API

Reviewed-on: Yadciel/c_tray#1

README.md

@@ -53,21 +53,23 @@ Execute the `tray_example` application:
 
 ## API
 
-Tray structure defines an icon and a menu.
+A tray is defined by an icon, an optional tooltip and a menu.
-Menu is a NULL-terminated array of items.
+The menu is a NULL-terminated array of items.
-Menu item defines menu text, menu checked and disabled (grayed) flags and a
+Each menu item can be disabled, checked, represented as a checkbox and invoke a
-callback with some optional context pointer.
+callback with an optional context pointer.
 
 ```c
 struct tray {
-  char *icon;
+  const char *icon;
+  char *tooltip;
   struct tray_menu *menu;
 };
 
 struct tray_menu {
-  char *text;
+  const char *text;
   int disabled;
   int checked;
+  int checkbox;
 
   void (*cb)(struct tray_menu *);
   void *context;
@@ -76,15 +78,23 @@ struct tray_menu {
 };
 ```
 
-* `int tray_init(struct tray *)` - creates tray icon. Returns -1 if tray icon/menu can't be created.
+* `int tray_init(struct tray *)` - creates the tray icon and its menu. Returns `-1` if the tray icon or menu cannot be created.
-* `void tray_update(struct tray *)` - updates tray icon and menu.
+* `void tray_update(struct tray *)` - updates the tray icon, tooltip and menu state.
-* `int tray_loop(int blocking)` - runs one iteration of the UI loop. Returns -1 if `tray_exit()` has been called.
+* `int tray_loop(int blocking)` - runs one iteration of the UI loop. Returns `-1` after `tray_exit()` has been called.
-* `void tray_exit()` - terminates UI loop.
+* `void tray_exit(void)` - terminates the UI loop and cleans up tray resources.
 
 All functions are meant to be called from the UI thread only.
 
-Menu arrays must be terminated with a NULL item, e.g. the last item in the
+Menu arrays must be terminated with a NULL item, i.e. the last item in the
-array must have text field set to NULL.
+array must have `text == NULL`.
+
+### Notes
+
+* `tooltip` is optional.
+* A separator is created by using `text = "-"`.
+* Some behavior may depend on the underlying backend or desktop environment.
+  Keep the public API generic and treat platform-specific interaction details as
+  backend-specific implementation behavior.
 
 ## License
 

tray.h

@@ -12,6 +12,10 @@ struct tray {
   const char *icon;
   char *tooltip;
   struct tray_menu *menu;
+  void *icon_handle;
+  int icon_is_shared;
+  void (*left_click_cb)(void *context);
+  void *left_click_context;
 };
 
 struct tray_menu {

tray_windows.c

@@ -10,6 +10,8 @@ static WNDCLASSEX wc;
 static NOTIFYICONDATA nid;
 static HWND hwnd;
 static HMENU hmenu = NULL;
+static struct tray *g_tray = NULL;
+static int g_icon_is_shared = 0;
 
 static LRESULT CALLBACK _tray_wnd_proc(HWND hwnd, UINT msg, WPARAM wparam,
                                        LPARAM lparam) {
@@ -21,7 +23,13 @@ static LRESULT CALLBACK _tray_wnd_proc(HWND hwnd, UINT msg, WPARAM wparam,
     PostQuitMessage(0);
     return 0;
   case WM_TRAY_CALLBACK_MESSAGE:
-    if (lparam == WM_LBUTTONUP || lparam == WM_RBUTTONUP) {
+    if (lparam == WM_LBUTTONUP) {
+      if (g_tray && g_tray->left_click_cb) {
+        g_tray->left_click_cb(g_tray->left_click_context);
+      }
+      return 0;
+    }
+    if (lparam == WM_RBUTTONUP) {
       POINT p;
       GetCursorPos(&p);
       SetForegroundWindow(hwnd);
@@ -106,6 +114,7 @@ int tray_init(struct tray *tray) {
   nid.uCallbackMessage = WM_TRAY_CALLBACK_MESSAGE;
   Shell_NotifyIcon(NIM_ADD, &nid);
 
+  g_tray = tray;
   tray_update(tray);
   return 0;
 }
@@ -126,18 +135,29 @@ int tray_loop(int blocking) {
 }
 
 void tray_update(struct tray *tray) {
+  g_tray = tray;
   HMENU prevmenu = hmenu;
   UINT id = ID_TRAY_FIRST;
   hmenu = _tray_menu(tray->menu, &id);
   SendMessage(hwnd, WM_INITMENUPOPUP, (WPARAM)hmenu, 0);
-  HICON icon;
+  HICON icon = NULL;
-  ExtractIconEx(tray->icon, 0, NULL, &icon, 1);
+  int icon_is_shared = 0;
-  if (nid.hIcon) {
+  if (tray->icon_handle) {
+    icon = (HICON)tray->icon_handle;
+    icon_is_shared = tray->icon_is_shared;
+  } else if (tray->icon) {
+    ExtractIconEx(tray->icon, 0, NULL, &icon, 1);
+  }
+  if (nid.hIcon && !g_icon_is_shared) {
     DestroyIcon(nid.hIcon);
   }
-  nid.hIcon = icon;
+  if (icon) {
+    nid.hIcon = icon;
+    g_icon_is_shared = icon_is_shared;
+  }
   if(tray->tooltip != 0 && strlen(tray->tooltip) > 0) {
-    strncpy(nid.szTip, tray->tooltip, sizeof(nid.szTip));
+    strncpy(nid.szTip, tray->tooltip, sizeof(nid.szTip) - 1);
+    nid.szTip[sizeof(nid.szTip) - 1] = '\0';
     nid.uFlags |= NIF_TIP;
   }
   Shell_NotifyIcon(NIM_MODIFY, &nid);
@@ -149,7 +169,7 @@ void tray_update(struct tray *tray) {
 
 void tray_exit(void) {
   Shell_NotifyIcon(NIM_DELETE, &nid);
-  if (nid.hIcon != 0) {
+  if (nid.hIcon != 0 && !g_icon_is_shared) {
     DestroyIcon(nid.hIcon);
   }
   if (hmenu != 0) {