docs: update docs

.changes/docs.md

@@ -0,0 +1,5 @@
+---
+"tray-icon": "patch"
+---
+
+Update docs.

Cargo.toml

@@ -6,7 +6,7 @@ description = "Create tray icons for desktop applications"
 homepage = "https://github.com/tauri-apps/tray-icon"
 repository = "https://github.com/tauri-apps/tray-icon"
 license = "MIT OR Apache-2.0"
-categories = [ "gui" ]
+categories = ["gui"]
 
 [dependencies]
 muda = "0.4"
@@ -21,7 +21,7 @@ features = [
   "Win32_Foundation",
   "Win32_System_SystemServices",
   "Win32_Graphics_Gdi",
-  "Win32_UI_Shell"
+  "Win32_UI_Shell",
 ]
 
 [target."cfg(target_os = \"linux\")".dependencies]
@@ -40,3 +40,7 @@ png = "0.17"
 winit = "0.28"
 tao = { git = "https://github.com/tauri-apps/tao", branch = "muda" }
 image = "0.24"
+eframe = "0.20.1"
+
+[target."cfg(target_os = \"linux\")".dev-dependencies]
+gtk = "0.16"

README.md

@@ -1,8 +1,37 @@
 tray-icon lets you create tray icons for desktop applications.
 
-# Example
+## Platforms supported:
 
-Create a tray icon without a menu.
+- Windows
+- macOS
+- Linux (gtk Only)
+
+## Platform-specific notes:
+
+- On Windows and Linux, an event loop must be running on the thread, on Windows, a win32 event loop and on Linux, a gtk event loop. It doesn't need to be the main thread but you have to create the tray icon on the same thread as the event loop.
+- On macOS, an event loop must be running on the main thread so you also need to create the tray icon on the main thread.
+
+## Dependencies (Linux Only)
+
+On Linux, `gtk` and `libappindicator` or `libayatnat-appindicator` are used to create the tray icon, so make sure to install them on your system.
+
+#### Arch Linux / Manjaro:
+
+```sh
+pacman -S gtk3 libappindicator-gtk3 #or libayatana-appindicator
+```
+
+#### Debian / Ubuntu:
+
+```sh
+sudo apt install libgtk-3-dev libappindicator3-dev #or libayatana-appindicator3-dev
+```
+
+if you use `tray_icon::muda` module, make sure to checkout https://github.com/tauri-apps/muda#dependencies
+
+## Examples
+
+#### Create a tray icon without a menu.
 
 ```rs
 use tray_icon::TrayIconBuilder;
@@ -14,9 +43,7 @@ let tray_icon = TrayIconBuilder::new()
     .unwrap();
 ```
 
-## Example
-
-Create a tray icon with a menu.
+#### Create a tray icon with a menu.
 
 ```rs
 use tray_icon::{TrayIconBuilder, menu::Menu};
@@ -34,6 +61,7 @@ let tray_icon = TrayIconBuilder::new()
 
 You can use `TrayEvent::receiver` to get a reference to the `TrayEventReceiver`
 which you can use to listen to events when a click happens on the tray icon
+
 ```rs
 use tray_icon::TrayEvent;
 

examples/egui.rs

@@ -0,0 +1,88 @@
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")] // hide console window on Windows in release
+
+use eframe::egui;
+use tray_icon::TrayIconBuilder;
+
+fn main() {
+    let path = concat!(env!("CARGO_MANIFEST_DIR"), "/examples/icon.png");
+    let icon = load_icon(std::path::Path::new(path));
+
+    #[cfg(target_os = "linux")]
+    std::thread::spawn(|| {
+        use tray_icon::menu::Menu;
+
+        gtk::init().unwrap();
+        let _tray_icon = TrayIconBuilder::new()
+            .with_menu(Box::new(Menu::new()))
+            .with_icon(icon)
+            .build()
+            .unwrap();
+
+        gtk::main();
+    });
+
+    #[cfg(not(target_os = "linux"))]
+    let _tray_icon = TrayIconBuilder::new().with_icon(icon).build().unwrap();
+
+    let options = eframe::NativeOptions {
+        initial_window_size: Some(egui::vec2(320.0, 240.0)),
+        ..Default::default()
+    };
+
+    eframe::run_native(
+        "My egui App",
+        options,
+        Box::new(|_cc| Box::<MyApp>::default()),
+    )
+}
+
+struct MyApp {
+    name: String,
+    age: u32,
+}
+
+impl Default for MyApp {
+    fn default() -> Self {
+        Self {
+            name: "Arthur".to_owned(),
+            age: 42,
+        }
+    }
+}
+
+impl eframe::App for MyApp {
+    fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
+        use tray_icon::TrayEvent;
+
+        if let Ok(event) = TrayEvent::receiver().try_recv() {
+            println!("tray event: {event:?}");
+        }
+
+        egui::CentralPanel::default().show(ctx, |ui| {
+            ui.heading("My egui Application");
+            ui.horizontal(|ui| {
+                let name_label = ui.label("Your name: ");
+                ui.text_edit_singleline(&mut self.name)
+                    .labelled_by(name_label.id);
+            });
+            ui.add(egui::Slider::new(&mut self.age, 0..=120).text("age"));
+            if ui.button("Click each year").clicked() {
+                self.age += 1;
+            }
+            ui.label(format!("Hello '{}', age {}", self.name, self.age));
+        });
+    }
+}
+
+fn load_icon(path: &std::path::Path) -> tray_icon::icon::Icon {
+    let (icon_rgba, icon_width, icon_height) = {
+        let image = image::open(path)
+            .expect("Failed to open icon path")
+            .into_rgba8();
+        let (width, height) = image.dimensions();
+        let rgba = image.into_raw();
+        (rgba, width, height)
+    };
+    tray_icon::icon::Icon::from_rgba(icon_rgba, icon_width, icon_height)
+        .expect("Failed to open icon")
+}

examples/tao.rs

@@ -52,11 +52,11 @@ fn main() {
                 tray_icon.take();
                 *control_flow = ControlFlow::Exit;
             }
-            println!("{:?}", event);
+            println!("{event:?}");
         }
 
         if let Ok(event) = tray_channel.try_recv() {
-            println!("{:?}", event);
+            println!("{event:?}");
         }
     })
 }

examples/winit.rs

@@ -52,11 +52,11 @@ fn main() {
                 tray_icon.take();
                 *control_flow = ControlFlow::Exit;
             }
-            println!("{:?}", event);
+            println!("{event:?}");
         }
 
         if let Ok(event) = tray_channel.try_recv() {
-            println!("{:?}", event);
+            println!("{event:?}");
         }
     })
 }

src/lib.rs

@@ -2,11 +2,41 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
+#![allow(clippy::uninlined_format_args)]
+
 //! tray-icon lets you create tray icons for desktop applications.
 //!
-//! # Example
+//! # Platforms supported:
+//!
+//! - Windows
+//! - macOS
+//! - Linux (gtk Only)
+//!
+//! # Platform-specific notes:
+//!
+//! - On Windows and Linux, an event loop must be running on the thread, on Windows, a win32 event loop and on Linux, a gtk event loop. It doesn't need to be the main thread but you have to create the tray icon on the same thread as the event loop.
+//! - On macOS, an event loop must be running on the main thread so you also need to create the tray icon on the main thread.
+//!
+//! # Dependencies (Linux Only)
+//!
+//! On Linux, `gtk` and `libappindicator` or `libayatnat-appindicator` are used to create the tray icon, so make sure to install them on your system.
+//!
+//! #### Arch Linux / Manjaro:
 //!
-//! Create a tray icon without a menu.
+//! ```sh
+//! pacman -S gtk3 libappindicator-gtk3 #or libayatana-appindicator
+//! ```
+//!
+//! #### Debian / Ubuntu:
+//!
+//! ```sh
+//! sudo apt install libgtk-3-dev libappindicator3-dev #or libayatana-appindicator3-dev
+//! ```
+//! if you use `tray_icon::muda` module, make sure to checkout https://github.com/tauri-apps/muda#dependencies
+//!
+//! # Examples
+//!
+//! #### Create a tray icon without a menu.
 //!
 //! ```no_run
 //! use tray_icon::{TrayIconBuilder, icon::Icon};
@@ -19,9 +49,7 @@
 //!     .unwrap();
 //! ```
 //!
-//! # Example
-//!
-//! Create a tray icon with a menu.
+//! #### Create a tray icon with a menu.
 //!
 //! ```no_run
 //! use tray_icon::{TrayIconBuilder, menu::Menu, icon::Icon};