lingxia_platform/traits/
app_runtime.rs

1use std::io::Read;
2use std::path::{Path, PathBuf};
3
4use crate::AssetFileEntry;
5use crate::error::PlatformError;
6
7use super::PlatformFuture;
8use super::device::{Device, DeviceHardware};
9use super::file::FileService;
10use super::location::Location;
11use super::media_interaction::{MediaInteraction, MediaKind};
12use super::media_runtime::MediaRuntime;
13use super::network::Network;
14use super::secure_store::SecureStore;
15use super::share::ShareService;
16use super::ui::{SurfacePresenter, UIUpdate, UserFeedback};
17use super::update::UpdateService;
18use super::wifi::Wifi;
19
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub enum AnimationType {
22    None = 0,
23    Forward = 1,
24    Backward = 2,
25}
26
27#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
28pub enum LxAppOpenMode {
29    #[default]
30    Normal = 0,
31    Panel = 1,
32}
33
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub enum OpenUrlTarget {
36    External = 0,
37    SelfTarget = 1,
38    /// Open a new browser tab unconditionally (skips "navigate current tab" heuristic).
39    NewBrowserTab = 2,
40    /// Open in the compact in-app browser as an API-managed aside tab. It uses
41    /// the one-row toolbar without address editing or user tab creation.
42    AsideBrowser = 3,
43}
44
45impl OpenUrlTarget {
46    pub fn parse(raw: Option<&str>) -> Self {
47        match raw.map(|v| v.trim().to_ascii_lowercase()) {
48            Some(v) if v == "self" => Self::SelfTarget,
49            Some(v) if v == "new_browser_tab" => Self::NewBrowserTab,
50            Some(v) if v == "aside" => Self::AsideBrowser,
51            Some(v) if v == "external" => Self::External,
52            Some(v) => {
53                log::warn!("Invalid openURL target='{}', fallback to external", v);
54                Self::External
55            }
56            None => Self::External,
57        }
58    }
59}
60
61#[derive(Debug, Clone)]
62pub struct OpenUrlRequest {
63    pub owner_appid: String,
64    pub owner_session_id: u64,
65    pub url: String,
66    pub target: OpenUrlTarget,
67    /// When true, the host should create the in-app tab before returning and
68    /// report its id. Fire-and-forget callers (new-window, navigation) leave
69    /// this false so the work can hop off a WebView UI thread.
70    pub want_tab_id: bool,
71}
72
73/// Outcome of [`AppRuntime::open_url`]. `tab_id` is set when the host named
74/// the tab it opened; `None` means the browser chrome owns the strip.
75#[derive(Debug, Clone, Default, PartialEq, Eq)]
76pub struct OpenUrlResult {
77    pub tab_id: Option<String>,
78}
79
80#[derive(Debug, Clone, Copy, PartialEq, Eq)]
81pub enum BuiltinBrowserPage {
82    Settings = 0,
83    Downloads = 1,
84}
85
86impl From<i32> for AnimationType {
87    fn from(value: i32) -> Self {
88        match value {
89            1 => AnimationType::Forward,
90            2 => AnimationType::Backward,
91            _ => AnimationType::None,
92        }
93    }
94}
95
96pub trait AppRuntime:
97    Send
98    + Sync
99    + MediaInteraction
100    + MediaRuntime
101    + Network
102    + SurfacePresenter
103    + Device
104    + DeviceHardware
105    + SecureStore
106    + ShareService
107    + FileService
108    + Location
109    + UIUpdate
110    + UpdateService
111    + UserFeedback
112    + Wifi
113    + 'static
114{
115    /// Reads an asset file as a streaming reader.
116    fn read_asset<'a>(&'a self, path: &str) -> Result<Box<dyn Read + 'a>, PlatformError>;
117
118    /// Iterates over files in an asset directory.
119    fn asset_dir_iter<'a>(
120        &'a self,
121        asset_dir: &str,
122    ) -> Box<dyn Iterator<Item = Result<AssetFileEntry<'a>, PlatformError>> + 'a>;
123
124    /// Returns the app's data directory path.
125    fn app_data_dir(&self) -> PathBuf;
126
127    /// Returns the app's cache directory path.
128    fn app_cache_dir(&self) -> PathBuf;
129
130    /// Obtains the application identifier.
131    fn get_app_identifier(&self) -> Result<String, PlatformError>;
132
133    /// Copies media from the system album to a local file.
134    fn copy_album_media_to_file(
135        &self,
136        uri: &str,
137        dest_path: &Path,
138        kind: MediaKind,
139    ) -> Result<(), PlatformError> {
140        MediaRuntime::copy_album_media_to_file(self, uri, dest_path, kind)
141    }
142
143    /// Returns the current system locale.
144    fn get_system_locale(&self) -> &str;
145
146    /// Show the UI container for the given LxApp and route.
147    /// `webtag` is the page instance's full webview tag; page tags are
148    /// per-instance, so shells must not reconstruct them from the route.
149    /// Platforms whose containers resolve through the runtime by path may
150    /// ignore it.
151    fn show_lxapp(
152        &self,
153        appid: String,
154        title: String,
155        path: String,
156        webtag: String,
157        session_id: u64,
158        open_mode: LxAppOpenMode,
159        panel_id: String,
160    ) -> Result<(), PlatformError>;
161
162    /// Notify the desktop skin that the next layout publication is an explicit
163    /// request to put this lxapp in front. Most skins reconcile directly from
164    /// the layout plan; Windows uses the intent to replace a browser cover
165    /// without treating unrelated resize/aside publications as activations.
166    fn request_lxapp_main_activation(&self, _appid: &str) {}
167
168    /// Hide the UI container for the given LxApp (does not destroy its runtime state).
169    fn hide_lxapp(&self, appid: String, session_id: u64) -> Result<(), PlatformError>;
170
171    /// Exits the host app.
172    fn exit(&self) -> Result<(), PlatformError>;
173
174    // Tray / badge chrome. These are cosmetic enhancements, so platforms that
175    // lack the chrome (e.g. no menu-bar tray on mobile) no-op rather than error —
176    // portable code can call them unconditionally. A supporting platform returns
177    // Err only on genuine failure.
178
179    /// Set the tray (menu-bar / system-tray) badge. Desktop only; no-op elsewhere.
180    fn set_tray_badge(&self, _text: &str) -> Result<(), PlatformError> {
181        Ok(())
182    }
183
184    /// Set the tray icon (a resource path). Desktop only; no-op elsewhere.
185    fn set_tray_icon(&self, _icon: &str) -> Result<(), PlatformError> {
186        Ok(())
187    }
188
189    /// Replace the resolved shell sidebar action render list. Desktop skins only
190    /// render presentation metadata and report stable ids.
191    fn set_shell_sidebar_actions(
192        &self,
193        _items: &[lingxia_shell::ResolvedShellSidebarAction],
194    ) -> Result<(), PlatformError> {
195        Ok(())
196    }
197
198    /// Replace the ordered mixed user Pin list. Platform skins resolve visual
199    /// metadata only; target identity and the eight-item limit are shell-owned.
200    fn set_shell_pins(&self, _items: &[lingxia_shell::ShellPin]) -> Result<(), PlatformError> {
201        Ok(())
202    }
203
204    /// Set the tray title (text beside the icon, macOS). Desktop only; no-op elsewhere.
205    fn set_tray_title(&self, _text: &str) -> Result<(), PlatformError> {
206        Ok(())
207    }
208
209    /// Set the app-icon badge: dock (macOS) / taskbar (Windows) / launcher icon
210    /// (iOS, Android). No-op on platforms where it is not yet wired.
211    fn set_app_badge(&self, _text: &str) -> Result<(), PlatformError> {
212        Ok(())
213    }
214
215    /// Whether the app is registered to launch at system startup. Only reached
216    /// on macOS/Windows — `lx.app.autostart` is not registered elsewhere — so
217    /// the default is an error, not a no-op: a false answer here would be a lie.
218    fn autostart_is_enabled(&self) -> Result<bool, PlatformError> {
219        Err(PlatformError::NotSupported("autostart".to_string()))
220    }
221
222    /// Register or unregister the app as a per-user startup item.
223    fn autostart_set_enabled(&self, _enabled: bool) -> Result<(), PlatformError> {
224        Err(PlatformError::NotSupported("autostart".to_string()))
225    }
226
227    /// Replace the tray dropdown menu. `items_json` is a JSON array of
228    /// `{ label?, separator?, enabled?, checked? }`. Item clicks are delivered
229    /// back to JS by index. Desktop only; no-op elsewhere.
230    fn set_tray_menu(&self, _items_json: &str) -> Result<(), PlatformError> {
231        Ok(())
232    }
233
234    /// Show or hide the tray status item itself. Desktop only; no-op elsewhere.
235    fn set_tray_visible(&self, _visible: bool) -> Result<(), PlatformError> {
236        Ok(())
237    }
238
239    /// When intercepting, a left-click on the tray is delivered only to JS
240    /// (`lx.tray.onClick`) and does not run the tray's configured surface action.
241    /// Desktop only; no-op elsewhere.
242    fn set_tray_click_intercept(&self, _intercept: bool) -> Result<(), PlatformError> {
243        Ok(())
244    }
245
246    /// Navigates within the given LxApp using an animation.
247    /// `webtag` is the destination page instance's full webview tag; page
248    /// tags are per-instance, so shells must not reconstruct them from the
249    /// route. Platforms whose containers resolve through the runtime by path
250    /// may ignore it.
251    fn navigate(
252        &self,
253        appid: String,
254        path: String,
255        webtag: String,
256        animation_type: AnimationType,
257    ) -> Result<(), PlatformError>;
258
259    /// Opens the given URL according to the host policy for the requested target.
260    fn open_url(&self, req: OpenUrlRequest) -> Result<OpenUrlResult, PlatformError>;
261
262    /// Close a tab previously named by [`Self::open_url`]. Platforms that
263    /// cannot name tabs leave this unimplemented — the JS handle then reports
264    /// `scope: 'group'` and never calls it.
265    fn close_browser_tab(&self, _tab_id: &str) -> Result<(), PlatformError> {
266        Err(PlatformError::NotSupported("browser tab".to_string()))
267    }
268
269    /// Bring a tab previously named by [`Self::open_url`] to the front.
270    fn activate_browser_tab(&self, _tab_id: String) -> PlatformFuture {
271        Box::pin(async { Err(PlatformError::NotSupported("browser tab".to_string())) })
272    }
273
274    fn open_builtin_browser_page(&self, _page: BuiltinBrowserPage) -> Result<(), PlatformError> {
275        Err(PlatformError::NotSupported(
276            "built-in browser pages".to_string(),
277        ))
278    }
279}
280
281#[cfg(test)]
282mod tests {
283    use super::OpenUrlTarget;
284
285    #[test]
286    fn parse_supports_new_browser_tab() {
287        assert_eq!(
288            OpenUrlTarget::parse(Some("new_browser_tab")),
289            OpenUrlTarget::NewBrowserTab
290        );
291    }
292
293    #[test]
294    fn parse_unknown_falls_back_to_external() {
295        assert_eq!(
296            OpenUrlTarget::parse(Some("foobar")),
297            OpenUrlTarget::External
298        );
299    }
300}
lingxia_platform/traits/app_runtime.rs

lingxia_platform/traits/
app_runtime.rs
