termux-gui 0.3.0

Rust bindings for Termux:GUI - Build Android GUI apps in Rust on Termux
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334

//! WebView component for displaying web content
//!
//! The WebView component allows you to display web pages and HTML content within your application,
//! with support for loading URLs, executing JavaScript, and more.
//!
//! # Important Usage Notes
//!
//! When displaying HTML content with dynamic effects, **you must enable JavaScript first**:
//!
//! ```no_run
//! use termux_gui_rust_demo::prelude::*;
//!
//! let mut activity = Activity::new()?;
//! let layout = LinearLayout::new(&mut activity, None, true)?;
//! let webview = WebView::new(&mut activity, Some(layout.id()))?;
//!
//! // ⚠️ Critical: Enable JavaScript first, or dynamic HTML content won't display
//! webview.allow_javascript(&mut activity, true)?;
//!
//! // Set HTML content
//! let html = r#"
//!     <html>
//!     <body style="background: purple;">
//!         <h1>Hello WebView!</h1>
//!     </body>
//!     </html>
//! "#;
//! webview.set_data(&mut activity, html)?;
//!
//! // Or load an external webpage
//! webview.load_uri(&mut activity, "https://www.google.com")?;
//! # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
//! ```

use serde_json::json;
use crate::activity::Activity;
use crate::view::View;
use crate::error::Result;

/// WebView component for displaying web content
///
/// # Important Usage Notes
///
/// 1. **JavaScript Support**: If your HTML content contains JavaScript or dynamic effects,
///    you must call `allow_javascript()` first to enable JavaScript, otherwise you may see
///    a blank page.
///
/// 2. **HTML Content Display Order**:
///    ```no_run
///    # use termux_gui_rust_demo::prelude::*;
///    # let mut activity = Activity::new()?;
///    # let webview = WebView::new(&mut activity, None)?;
///    // Step 1: Enable JavaScript (if needed)
///    webview.allow_javascript(&mut activity, true)?;
///    
///    // Step 2: Set HTML content
///    webview.set_data(&mut activity, "<html>...</html>")?;
///    # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
///    ```
///
/// 3. **Loading External URLs**: Simply call `load_uri()` - no special order required
///
/// # Examples
///
/// ```no_run
/// use termux_gui_rust_demo::prelude::*;
///
/// let mut activity = Activity::new()?;
/// let webview = WebView::new(&mut activity, None)?;
///
/// // Method 1: Display HTML content (requires JavaScript to be enabled first)
/// webview.allow_javascript(&mut activity, true)?;
/// webview.set_data(&mut activity, "<html><body><h1>Hello</h1></body></html>")?;
///
/// // Method 2: Load a webpage
/// webview.load_uri(&mut activity, "https://www.example.com")?;
/// # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
/// ```
pub struct WebView {
    view: View,
    aid: i64,
}

impl WebView {
    /// Creates a new WebView
    ///
    /// # Arguments
    /// - `activity`: Reference to the Activity
    /// - `parent`: Optional parent view ID
    ///
    /// # Examples
    /// ```no_run
    /// # use termux_gui_rust_demo::prelude::*;
    /// # let mut activity = Activity::new()?;
    /// # let layout_id = 0;
    /// let webview = WebView::new(&mut activity, Some(layout_id))?;
    /// # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
    /// ```
    pub fn new(activity: &mut Activity, parent: Option<i64>) -> Result<Self> {
        eprintln!("[DEBUG] WebView::new() - creating WebView...");
        
        let mut params = json!({
            "aid": activity.id()
        });
        
        if let Some(parent_id) = parent {
            params["parent"] = json!(parent_id);
        }
        
        eprintln!("[DEBUG] WebView::new() - sending createWebView...");
        let response = activity.send_read(&json!({
            "method": "createWebView",
            "params": params
        }))?;
        
        eprintln!("[DEBUG] WebView::new() - got response: {:?}", response);
        
        let id = response
            .as_i64()
            .ok_or_else(|| crate::error::GuiError::InvalidResponse("Invalid id".to_string()))?;
        
        Ok(WebView {
            view: View::new(id),
            aid: activity.id(),
        })
    }
    
    /// Gets the view ID
    pub fn id(&self) -> i64 {
        self.view.id()
    }
    
    /// Gets a reference to the underlying View
    pub fn view(&self) -> &View {
        &self.view
    }
    
    /// Loads a URI/URL
    ///
    /// # Arguments
    /// - `activity`: Reference to the Activity
    /// - `uri`: The URL to load, e.g., "https://www.google.com"
    ///
    /// # Examples
    /// ```no_run
    /// # use termux_gui_rust_demo::prelude::*;
    /// # let mut activity = Activity::new()?;
    /// # let webview = WebView::new(&mut activity, None)?;
    /// webview.load_uri(&mut activity, "https://www.google.com")?;
    /// # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
    /// ```
    pub fn load_uri(&self, activity: &mut Activity, uri: &str) -> Result<()> {
        activity.send(&json!({
            "method": "loadURI",
            "params": {
                "aid": self.aid,
                "id": self.view.id(),
                "uri": uri
            }
        }))?;
        Ok(())
    }
    
    /// Sets HTML content
    ///
    /// ⚠️ **Important**: If the HTML contains JavaScript or dynamic effects, you must call
    /// `allow_javascript(true)` first, otherwise you may see a blank page.
    ///
    /// # Arguments
    /// - `activity`: Reference to the Activity
    /// - `data`: The HTML document content
    ///
    /// # Examples
    /// ```no_run
    /// # use termux_gui_rust_demo::prelude::*;
    /// # let mut activity = Activity::new()?;
    /// # let webview = WebView::new(&mut activity, None)?;
    /// // If HTML contains JavaScript, enable it first
    /// webview.allow_javascript(&mut activity, true)?;
    /// 
    /// // Then set the HTML content
    /// webview.set_data(&mut activity, "<html><body><h1>Hello</h1></body></html>")?;
    /// # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
    /// ```
    pub fn set_data(&self, activity: &mut Activity, data: &str) -> Result<()> {
        // Use base64 encoding to support HTML content with non-ASCII characters
        let encoded = base64::Engine::encode(&base64::engine::general_purpose::STANDARD, data.as_bytes());
        
        activity.send(&json!({
            "method": "setData",
            "params": {
                "aid": self.aid,
                "id": self.view.id(),
                "doc": encoded,
                "base64": true
            }
        }))?;
        Ok(())
    }
    
    /// Allows JavaScript execution
    ///
    /// ⚠️ **Important**: When displaying HTML with JavaScript or dynamic effects, you must
    /// call this method first to enable JavaScript.
    ///
    /// If JavaScript is requested to be enabled, a user confirmation dialog will appear,
    /// and the user can deny the request. This method blocks until the user responds.
    ///
    /// # Arguments
    /// - `activity`: Reference to the Activity
    /// - `allow`: Whether to allow JavaScript
    ///
    /// # Returns
    /// Returns whether JavaScript is enabled after the call (if the user denies,
    /// it will return false even if you passed true)
    ///
    /// # Examples
    /// ```no_run
    /// # use termux_gui_rust_demo::prelude::*;
    /// # let mut activity = Activity::new()?;
    /// # let webview = WebView::new(&mut activity, None)?;
    /// // Enable JavaScript (requires user confirmation)
    /// let enabled = webview.allow_javascript(&mut activity, true)?;
    /// if enabled {
    ///     println!("JavaScript enabled");
    ///     // Now you can set HTML with JavaScript
    ///     webview.set_data(&mut activity, "<html><body><script>alert('Hi!');</script></body></html>")?;
    /// }
    /// # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
    /// ```
    pub fn allow_javascript(&self, activity: &mut Activity, allow: bool) -> Result<bool> {
        let response = activity.send_read(&json!({
            "method": "allowJavascript",
            "params": {
                "aid": self.aid,
                "id": self.view.id(),
                "allow": allow
            }
        }))?;
        
        Ok(response.as_bool().unwrap_or(false))
    }
    
    /// Allows loading content from content:// URIs
    ///
    /// # Arguments
    /// - `activity`: Reference to the Activity
    /// - `allow`: Whether to allow loading from content URIs
    pub fn allow_content_uri(&self, activity: &mut Activity, allow: bool) -> Result<()> {
        activity.send(&json!({
            "method": "allowContentURI",
            "params": {
                "aid": self.aid,
                "id": self.view.id(),
                "allow": allow
            }
        }))?;
        Ok(())
    }
    
    /// Allows navigation to different sites
    ///
    /// # Arguments
    /// - `activity`: Reference to the Activity
    /// - `allow`: Whether to allow users and JavaScript to navigate to different sites
    pub fn allow_navigation(&self, activity: &mut Activity, allow: bool) -> Result<()> {
        activity.send(&json!({
            "method": "allowNavigation",
            "params": {
                "aid": self.aid,
                "id": self.view.id(),
                "allow": allow
            }
        }))?;
        Ok(())
    }
    
    /// Executes JavaScript code in the WebView
    ///
    /// ⚠️ **Prerequisite**: You must enable JavaScript via `allow_javascript(true)` first,
    /// otherwise the code will not execute.
    ///
    /// # Arguments
    /// - `activity`: Reference to the Activity
    /// - `code`: The JavaScript code to execute
    ///
    /// # Examples
    /// ```no_run
    /// # use termux_gui_rust_demo::prelude::*;
    /// # let mut activity = Activity::new()?;
    /// # let webview = WebView::new(&mut activity, None)?;
    /// // Step 1: Enable JavaScript
    /// webview.allow_javascript(&mut activity, true)?;
    ///
    /// // Step 2: Execute JavaScript code
    /// webview.evaluate_js(&mut activity, "document.body.style.background = 'red';")?;
    /// # Ok::<(), termux_gui_rust_demo::error::GuiError>(())
    /// ```
    pub fn evaluate_js(&self, activity: &mut Activity, code: &str) -> Result<()> {
        activity.send(&json!({
            "method": "evaluateJS",
            "params": {
                "aid": self.aid,
                "id": self.view.id(),
                "code": code
            }
        }))?;
        Ok(())
    }
    
    /// Goes back to the previous page in history
    pub fn go_back(&self, activity: &mut Activity) -> Result<()> {
        activity.send(&json!({
            "method": "goBack",
            "params": {
                "aid": self.aid,
                "id": self.view.id()
            }
        }))?;
        Ok(())
    }
    
    /// Goes forward to the next page in history
    pub fn go_forward(&self, activity: &mut Activity) -> Result<()> {
        activity.send(&json!({
            "method": "goForward",
            "params": {
                "aid": self.aid,
                "id": self.view.id()
            }
        }))?;
        Ok(())
    }
}