tao 0.16.11

Cross-platform window manager library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

// Copyright 2014-2021 The winit contributors
// Copyright 2021-2023 Tauri Programme within The Commons Conservancy
// SPDX-License-Identifier: Apache-2.0

//! **UNSTABLE** -- The `SystemTray` struct and associated types.
//!
//! Use [SystemTrayBuilder][tray_builder] to create your tray instance.
//!
//! [ContextMenu][context_menu] is used to created a Window menu on Windows and Linux. On macOS it's used in the menubar.
//!
//! ```rust,ignore
//! # let icon_rgba = Vec::<u8>::new();
//! # let icon_width = 0;
//! # let icon_height = 0;
//! let mut tray_menu = ContextMenu::new();
//! let icon = Icon::from_rgba(icon_rgba, icon_width, icon_height);
//!
//! tray_menu.add_item(MenuItemAttributes::new("My menu item"));
//!
//! let mut system_tray = SystemTrayBuilder::new(icon, Some(tray_menu))
//!   .build(&event_loop)
//!   .unwrap();
//! ```
//!
//! # Linux
//! A menu is required or the tray return an error containing `assertion 'G_IS_DBUS_CONNECTION (connection)'`.
//!
//! [tray_builder]: crate::system_tray::SystemTrayBuilder
//! [menu_bar]: crate::menu::MenuBar
//! [context_menu]: crate::menu::ContextMenu

use crate::{
  error::OsError,
  event_loop::EventLoopWindowTarget,
  menu::ContextMenu,
  platform_impl::{
    SystemTray as SystemTrayPlatform, SystemTrayBuilder as SystemTrayBuilderPlatform,
  },
  TrayId,
};

pub use crate::icon::{BadIcon, Icon};

/// Object that allows you to build SystemTray instance.
pub struct SystemTrayBuilder {
  pub(crate) platform_tray_builder: SystemTrayBuilderPlatform,
  tooltip: Option<String>,
  id: TrayId,
}

impl SystemTrayBuilder {
  /// Creates a new SystemTray with an empty identifier for platforms where this is appropriate.
  pub fn new(icon: Icon, tray_menu: Option<ContextMenu>) -> Self {
    Self {
      platform_tray_builder: SystemTrayBuilderPlatform::new(
        icon,
        tray_menu.map(|m| m.0.menu_platform),
      ),
      tooltip: None,
      id: TrayId::EMPTY,
    }
  }

  /// Sets the tray identifier.
  pub fn with_id(mut self, id: TrayId) -> Self {
    self.id = id;
    self
  }

  /// Adds a tooltip for this tray icon.
  ///
  /// ## Platform-specific:
  ///
  /// - **Linux:** Unsupported
  pub fn with_tooltip(mut self, tooltip: &str) -> Self {
    self.tooltip = Some(tooltip.to_string());
    self
  }

  /// Builds the SystemTray.
  ///
  /// Possible causes of error include denied permission, incompatible system, and lack of memory.
  pub fn build<T: 'static>(
    self,
    window_target: &EventLoopWindowTarget<T>,
  ) -> Result<SystemTray, OsError> {
    self
      .platform_tray_builder
      .build(window_target, self.id, self.tooltip)
  }
}

/// Represents a System Tray instance.
///
/// ## Drop behavior
///
/// **Linux:**
///   - Dropping the tray too early could lead to a default icon.
///   - Dropping the tray hides it.
/// **Windows / macOS:** Dropping the tray will effectively remove the icon from the system tray.
pub struct SystemTray(pub SystemTrayPlatform);

impl SystemTray {
  /// Set new tray icon.
  pub fn set_icon(&mut self, icon: Icon) {
    self.0.set_icon(icon)
  }

  /// Set new tray menu.
  pub fn set_menu(&mut self, tray_menu: &ContextMenu) {
    self.0.set_menu(&tray_menu.0.menu_platform)
  }

  /// Sets the tooltip for this tray icon.
  ///
  /// ## Platform-specific:
  ///
  /// - **Linux:** Unsupported
  pub fn set_tooltip(&mut self, tooltip: &str) {
    self.0.set_tooltip(tooltip);
  }
}