From 258b49aaebd81b6e4327cca1a1a0a2d9bb64188a Mon Sep 17 00:00:00 2001 From: amrbashir Date: Wed, 8 Feb 2023 21:15:28 +0200 Subject: [PATCH] docs: update docs --- .changes/docs.md | 5 +++ Cargo.toml | 8 +++-- README.md | 38 +++++++++++++++++--- examples/egui.rs | 88 +++++++++++++++++++++++++++++++++++++++++++++++ examples/tao.rs | 4 +-- examples/winit.rs | 4 +-- src/lib.rs | 38 +++++++++++++++++--- 7 files changed, 169 insertions(+), 16 deletions(-) create mode 100644 .changes/docs.md create mode 100644 examples/egui.rs diff --git a/.changes/docs.md b/.changes/docs.md new file mode 100644 index 0000000..34d8244 --- /dev/null +++ b/.changes/docs.md @@ -0,0 +1,5 @@ +--- +"tray-icon": "patch" +--- + +Update docs. diff --git a/Cargo.toml b/Cargo.toml index 579cbc8..3a37b6c 100644 --- a/Cargo.toml +++ b/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" diff --git a/README.md b/README.md index 419c3a9..bc252f0 100644 --- a/README.md +++ b/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; diff --git a/examples/egui.rs b/examples/egui.rs new file mode 100644 index 0000000..149e52c --- /dev/null +++ b/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::::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") +} diff --git a/examples/tao.rs b/examples/tao.rs index de4d524..d77771c 100644 --- a/examples/tao.rs +++ b/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:?}"); } }) } diff --git a/examples/winit.rs b/examples/winit.rs index 7d9475e..20f45fd 100644 --- a/examples/winit.rs +++ b/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:?}"); } }) } diff --git a/src/lib.rs b/src/lib.rs index aa51de4..f5e1709 100644 --- a/src/lib.rs +++ b/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};