diff --git a/docs/images/modals_dynamic_notification.png b/docs/images/modals_dynamic_notification.png new file mode 100644 index 000000000..bbc232f67 Binary files /dev/null and b/docs/images/modals_dynamic_notification.png differ diff --git a/docs/images/modals_get_checkbox.png b/docs/images/modals_get_checkbox.png new file mode 100644 index 000000000..53db571f3 Binary files /dev/null and b/docs/images/modals_get_checkbox.png differ diff --git a/docs/images/modals_get_radiobutton.png b/docs/images/modals_get_radiobutton.png new file mode 100644 index 000000000..0e5e14005 Binary files /dev/null and b/docs/images/modals_get_radiobutton.png differ diff --git a/docs/images/modals_input_bip39_1.png b/docs/images/modals_input_bip39_1.png new file mode 100644 index 000000000..67ddcf6ab Binary files /dev/null and b/docs/images/modals_input_bip39_1.png differ diff --git a/docs/images/modals_input_bip39_2.png b/docs/images/modals_input_bip39_2.png new file mode 100644 index 000000000..b59d5ef7a Binary files /dev/null and b/docs/images/modals_input_bip39_2.png differ diff --git a/docs/images/modals_input_bip39_3.png b/docs/images/modals_input_bip39_3.png new file mode 100644 index 000000000..0a8449ec5 Binary files /dev/null and b/docs/images/modals_input_bip39_3.png differ diff --git a/docs/images/modals_show_bip39.png b/docs/images/modals_show_bip39.png new file mode 100644 index 000000000..bfdbc341f Binary files /dev/null and b/docs/images/modals_show_bip39.png differ diff --git a/docs/images/modals_slider.png b/docs/images/modals_slider.png new file mode 100644 index 000000000..8606e6118 Binary files /dev/null and b/docs/images/modals_slider.png differ diff --git a/docs/images/modals_start_progress.png b/docs/images/modals_start_progress.png new file mode 100644 index 000000000..1c948437c Binary files /dev/null and b/docs/images/modals_start_progress.png differ diff --git a/services/modals/src/lib.rs b/services/modals/src/lib.rs index 5b3f1bc9f..92c407d0b 100644 --- a/services/modals/src/lib.rs +++ b/services/modals/src/lib.rs @@ -243,9 +243,30 @@ impl Modals { Ok(()) } - /// this blocks until the notification has been acknowledged. It will attempt to render up to 256 bits - /// of `data` in bip39 format. Data must conform to the codeable lengths by BIP39, or else the routine + /// Modal dialog used to show up to 256 bits of `data` in bip39 format. + /// + /// - This dialog blocks until the notification has been acknowledged via [ Press any key ]. + /// - Data must conform to the codeable lengths by BIP39, or else the routine /// will return immediately with an `InvalidString` error without showing any dialog box. + /// + ///
+ /// Example Image + /// + /// ![Example Image](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_show_bip39.png?raw=true) + /// + ///
+ /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// let refnum = 0b00000110001101100111100111001010000110110010100010110101110011111101101010011100000110000110101100110110011111100010011100011110u128; + /// let refvec = refnum.to_be_bytes().to_vec(); + /// modals.show_bip39(Some("Some bip39 words"), &refvec).expect("couldn't show bip39 words"); + /// ``` pub fn show_bip39(&self, caption: Option<&str>, data: &Vec) -> Result<(), xous::Error> { match data.len() { 16 | 20 | 24 | 28 | 32 => (), @@ -268,6 +289,41 @@ impl Modals { Ok(()) } + /// Input dialog used to accept bip39 formatted data. + /// + /// - This dialog blocks until either \[ F4 \] has been pressed to abort entry, or a phrase has been input + /// and accepted via \[ enter \]. + /// - Possible words will be auto-suggested during typing and \[ enter \] must be pressed after each word. + /// - Valid input will be shown in the bottom section of the dialog after an accepted phrase has been + /// entered. + /// + ///
+ /// Example Images (from example code below) + /// + /// ![Example Image - Initial](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_input_bip39_1.png?raw=true) + /// ![Example Image - Input](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_input_bip39_2.png?raw=true) + /// ![Example Image - Confirmation](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_input_bip39_3.png?raw=true) + /// + ///
+ /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// log::info!( + /// "type these words: alert record income curve mercy tree heavy loan hen recycle mean devote" + /// ); + /// match modals.input_bip39(Some("Input BIP39 words")) { + /// Ok(data) => { + /// log::info!("got bip39 input: {:x?}", data); + /// log::info!("reference: 0x063679ca1b28b5cfda9c186b367e271e"); + /// } + /// Err(e) => log::error!("couldn't get input: {:?}", e), + /// } + /// ``` pub fn input_bip39(&self, prompt: Option<&str>) -> Result, xous::Error> { self.lock(); let spec = ManagedBip39 { @@ -287,7 +343,13 @@ impl Modals { } } - /// this blocks until the image has been dismissed. + /// Shows image. + /// - Blocks until the image has been dismissed. + /// + /// [Code Example - procedurally generate image](https://github.com/betrusted-io/xous-core/blob/c84f4efba0d4a5ae690f147c57590134d3cafc27/services/modals/src/tests.rs#L174-L201) + /// [Code Example - show_image for procedurally generated](https://github.com/betrusted-io/xous-core/blob/c84f4efba0d4a5ae690f147c57590134d3cafc27/services/modals/src/tests.rs#L155-L163) + /// + /// [Code Example - show_image for downloaded image](https://github.com/betrusted-io/xous-core/blob/c84f4efba0d4a5ae690f147c57590134d3cafc27/services/shellchat/src/cmds/net_cmd.rs#L378-L483) #[cfg(feature = "ditherpunk")] pub fn show_image(&self, mut bm: Bitmap) -> Result<(), xous::Error> { self.lock(); @@ -317,6 +379,29 @@ impl Modals { Ok(()) } + /// Generates progress bar (updated by update_progress, and closed by finish_progress). + /// + /// - This item cannot be dismissed/modified by the user. + /// - If 'current' is less than 'start' or more than 'end', progress will show 0 or 100 percent, + /// respectively. + /// - Title text wraps, burden is on the consumer not to exceed the available screen space. + /// + ///
+ /// Example Image + /// + /// ![Example Image](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_start_progress.png?raw=true) + /// + ///
+ /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// modals.start_progress("Progress Quest", 0, 1000, 0).expect("couldn't raise progress bar"); + /// ``` pub fn start_progress(&self, title: &str, start: u32, end: u32, current: u32) -> Result<(), xous::Error> { self.lock(); let spec = ManagedProgress { @@ -333,6 +418,32 @@ impl Modals { Ok(()) } + /// Human interaction-enabled slider. + /// + /// - Interactable until home/enter is pressed. + /// - Use the D-pad to shift the slider by a step in either direction. + /// - Note that it is possible to exceed start or end if you choose the 'step' value poorly. + /// - Title text wraps, burden is on the consumer not to exceed available screen space. + /// + ///
+ /// Example Image + /// + /// ![Example Image](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_slider.png?raw=true) + /// + ///
+ /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// let result = modals + /// .slider("Human interaction-enabled slider!", 0, 100, 50, 1) + /// .expect("slider test failed"); + /// log::info!("result: {}", &result); + /// ``` pub fn slider( &self, title: &str, @@ -360,9 +471,39 @@ impl Modals { Ok(orig.0) } - /// note that this API is not atomically token-locked, so, someone could mess with the progress bar state - /// but, progress updates are meant to be fast and frequent, and generally if a progress bar shows - /// something whacky it's not going to affect a security outcome + /// Updates progress bar (created by start_progress, and closed by finish_progress). + /// + /// - This item cannot be dismissed/modified by the user. + /// - If you exceed 'end' of the progress bar with an update, it will show 100%. + /// - Note that this API is not atomically token-locked, so, someone could mess with the progress bar + /// state. But, progress updates are meant to be fast and frequent, and generally if a progress bar + /// shows something whacky it's not going to affect a security outcome. + /// + /// - suggestions for if you run into the queue overflow error: + /// - preferred: reduce the rate at which updates occur by modifying the updater code to do less + /// frequent updates. For example, instead of once every iteration of a loop, once every ten + /// iterations. This will improve performance of the code and reduce UI churn as well. If this is not + /// possible, you can add a sleep by doing something like the code below. This will reduce the rate at + /// which your loop runs, as well as at which the UI updates. + /// ``` + /// std::thread::sleep(std::time::Duration::from_millis(100)); + /// ``` + /// - An alternative "softer" solution is to call yield. This will cause the producer to yield its time + /// slice to other processes in the OS, which can give the progress bar a chance to catch up. + /// ``` + /// xous::yield_slice(); + /// ``` + /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// modals.start_progress("Progress Quest", 0, 1000, 0).expect("couldn't raise progress bar"); + /// modals.update_progress(10).expect("couldn't update progress bar"); + /// ``` pub fn update_progress(&self, current: u32) -> Result<(), xous::Error> { match xous::try_send_message( self.conn, @@ -371,19 +512,34 @@ impl Modals { Ok(_) => (), Err(e) => { log::warn!("update_progress failed with {:?}, skipping request", e); - // most likely issue is that the server queue is overfull because too many progress updates - // were sent sleep the sending thread to rate-limit requests, while discarding - // the current request. + // We got here because the modals inbound server queue has overflowed. The most likely reason + // is that too many progress updates were sent. The yield statement below causes the sending + // thread to sleep for the rest of its scheduling quantum, thus rate-limiting requests. The + // current request is simply discarded; no attempt is made to retry. xous::yield_slice() } } Ok(()) } - /// Close the progress bar, regardless of the current state - /// This is a blocking call, because you want the GAM to revert focus back to your context before you - /// continue with any drawing operations. Otherwise, they could be missed as the modal is still covering - /// your window. + /// Closes progress bar (created by start_progress, and updated by update_progress). + /// + /// - Closes the progress bar, regardless of the current state. + /// - This is a blocking call, because you want the GAM to revert focus back to your context before you + /// continue with any drawing operations. Otherwise, they could be missed as the modal is still + /// covering your window. + /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// modals.start_progress("Progress Quest", 0, 1000, 0).expect("couldn't raise progress bar"); + /// modals.update_progress(10).expect("couldn't update progress bar"); + /// modals.finish_progress().expect("couldn't dismiss progress bar"); + /// ``` pub fn finish_progress(&self) -> Result<(), xous::Error> { self.lock(); send_message( @@ -401,6 +557,28 @@ impl Modals { Ok(()) } + /// Creates a list to be used by get_radiobutton or get_checkbox. + /// - Does not display on its own, the above mentioned methods prompt display of the list. + /// - Burden is on the consumer to not exceed available screen space. + /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// const LIST_TEST: [&'static str; 5] = [ + /// "happy", + /// "😃", + /// "安", + /// "peace &\n tranquility", + /// "Once apon a time, in a land far far away, there was a", + /// ]; + /// + /// let items: Vec<&str> = LIST_TEST.iter().map(|s| s.to_owned()).collect(); + /// modals.add_list(items).expect("couldn't build list"); + /// ``` pub fn add_list(&self, items: Vec<&str>) -> Result<(), xous::Error> { for (_, text) in items.iter().enumerate() { self.add_list_item(text).or(Err(xous::Error::InternalError))?; @@ -408,6 +586,19 @@ impl Modals { Ok(()) } + /// Add individual items to a list to be used by get_radiobutton or get_checkbox. + /// - Does not display on its own, the above mentioned methods prompt display of the list. + /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// modals.add_list_item("yes").expect("failed radio yes"); + /// modals.add_list_item("no").expect("failed radio no"); + /// ``` pub fn add_list_item(&self, item: &str) -> Result<(), xous::Error> { self.lock(); let itemname = ManagedListItem { token: self.token, item: ItemName::new(item) }; @@ -416,6 +607,36 @@ impl Modals { Ok(()) } + /// Creates modal dialog from list of items (list created by add_list or add_list_item) and returns String + /// value of selected item. + /// - Dialog cannot be dismissed without pressing 'ok'. + /// - 'ok' text is not editable. + /// - Any or none of the checked items are acceptable to be returned. + /// + ///
+ /// Example Image + /// + /// ![Example Image](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_get_radiobutton.png?raw=true) + /// + ///
+ /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// const RADIO_TEST: [&'static str; 4] = ["zebra", "cow", "horse", "cat"]; + /// + /// for item in RADIO_TEST { + /// modals.add_list_item(item).expect("couldn't build radio item list"); + /// } + /// match modals.get_radiobutton("Pick an animal") { + /// Ok(animal) => log::info!("{} was picked", animal), + /// _ => log::error!("get_radiobutton failed"), + /// } + /// ``` pub fn get_radiobutton(&self, prompt: &str) -> Result { self.lock(); let spec = @@ -428,6 +649,26 @@ impl Modals { Ok(String::from(itemname.as_str())) } + /// Gets selected index of radio button, *after* ok is pressed on get_radiobutton. + /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// const RADIO_TEST: [&'static str; 4] = ["zebra", "cow", "horse", "cat"]; + /// + /// for item in RADIO_TEST { + /// modals.add_list_item(item).expect("couldn't build radio item list"); + /// } + /// match modals.get_radiobutton("Pick an animal") { + /// Ok(animal) => log::info!("{} was picked", animal), + /// _ => log::error!("get_radiobutton failed"), + /// } + /// log::info!("Radio index selected = {:?}", modals.get_radio_index().unwrap()); + /// ``` pub fn get_radio_index(&self) -> Result { let msg = Message::new_blocking_scalar(Opcode::GetModalIndex.to_usize().unwrap(), 0, 0, 0, 0); match send_message(self.conn, msg) { @@ -442,6 +683,46 @@ impl Modals { } } + /// Creates modal dialog from list of items (list created by add_list or add_list_item) and returns Vector + /// of checked items. + /// - Dialog cannot be dismissed without pressing 'ok'. + /// - 'ok' text is not editable. + /// - Any or none of the checked items are acceptable to be returned. + /// + ///
+ /// Example Image + /// + /// ![Example Image](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_get_checkbox.png?raw=true) + /// + ///
+ /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// const LIST_TEST: [&'static str; 5] = [ + /// "happy", + /// "😃", + /// "安", + /// "peace &\n tranquility", + /// "Once apon a time, in a land far far away, there was a", + /// ]; + /// + /// let items: Vec<&str> = LIST_TEST.iter().map(|s| s.to_owned()).collect(); + /// modals.add_list(items).expect("couldn't build list"); + /// match modals.get_checkbox("You can have it all:") { + /// Ok(things) => { + /// log::info!("The user picked {} things:", things.len()); + /// for thing in things { + /// log::info!("{}", thing); + /// } + /// } + /// _ => log::error!("get_checkbox failed"), + /// } + /// ``` pub fn get_checkbox(&self, prompt: &str) -> Result, xous::Error> { self.lock(); let spec = @@ -460,6 +741,36 @@ impl Modals { Ok(ret) } + /// Gets Vector of indices of checked items, *after* ok is pressed on get_checkbox. + /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// const LIST_TEST: [&'static str; 5] = [ + /// "happy", + /// "😃", + /// "安", + /// "peace &\n tranquility", + /// "Once apon a time, in a land far far away, there was a", + /// ]; + /// + /// let items: Vec<&str> = LIST_TEST.iter().map(|s| s.to_owned()).collect(); + /// modals.add_list(items).expect("couldn't build list"); + /// match modals.get_checkbox("You can have it all:") { + /// Ok(things) => { + /// log::info!("The user picked {} things:", things.len()); + /// for thing in things { + /// log::info!("{}", thing); + /// } + /// } + /// _ => log::error!("get_checkbox failed"), + /// } + /// log::info!("Checkbox indices selected = {:?}", modals.get_check_index()); + /// ``` pub fn get_check_index(&self) -> Result, xous::Error> { let mut ret = Vec::::new(); let msg = Message::new_blocking_scalar(Opcode::GetModalIndex.to_usize().unwrap(), 0, 0, 0, 0); @@ -478,6 +789,37 @@ impl Modals { } } + /// Notification modal with title and text that can be updated. + /// - Modal cannot be dismissed by the user, you must close this dialog using `dynamic_notification_close` + /// - Burden is on the consumer to not exceed available space. + /// + ///
+ /// Example Image + /// + /// ![Example Image](https://github.com/betrusted-io/xous-core/blob/main/docs/images/modals_dynamic_notification.png?raw=true) + /// + ///
+ /// + /// # Example + /// ``` + /// use modals::Modals; + /// use xous_names::XousNames; + /// let xns = XousNames::new().unwrap(); + /// let modals = Modals::new(&xns).unwrap(); + /// + /// modals + /// .dynamic_notification(Some("TITLE OF NOTIFICATION"), Some("Important details go here...")) + /// .unwrap(); + /// // do some stuff + /// modals + /// .dynamic_notification_update( + /// Some("Important update!"), + /// Some("We're almost there, please hold.."), + /// ) + /// .unwrap(); + /// // do more stuff + /// modals.dynamic_notification_close().unwrap(); + /// ``` pub fn dynamic_notification(&self, title: Option<&str>, text: Option<&str>) -> Result<(), xous::Error> { self.lock(); let spec = DynamicNotification { @@ -491,6 +833,8 @@ impl Modals { Ok(()) } + /// - Calling this to update the dynamic_notification dialog is optional. + /// - See documentation for `dynamic_notification` for a code example. pub fn dynamic_notification_update( &self, title: Option<&str>, @@ -507,6 +851,8 @@ impl Modals { Ok(()) } + /// - You must call this method to dismiss `dynamic_notification` when it is no longer needed. + /// - See documentation for `dynamic_notification` for a code example. pub fn dynamic_notification_close(&self) -> Result<(), xous::Error> { send_message( self.conn, @@ -553,10 +899,14 @@ impl Modals { fn unlock(&self) { self.have_lock.set(false); } + /// - needed for use with `dynamic_notification_blocking_listener` + /// - see `dynamic_notification_blocking_listener` for a code example. pub fn conn(&self) -> CID { self.conn } /// Don't leak this token outside of your server, otherwise, another server can pretend to be you and /// steal your modal information! + /// - needed for use with `dynamic_notification_blocking_listener` + /// - see `dynamic_notification_blocking_listener` for a code example. pub fn token(&self) -> [u32; 4] { self.token } } @@ -587,6 +937,48 @@ impl Drop for Modals { /// /// This function is "broken out" so that it can be called from a thread without having /// to wrap a mutex around the primary Modals structure. +/// +/// # Example +/// ``` +/// use core::sync::atomic::{AtomicU32, Ordering}; +/// use std::sync::Arc; +/// use modals::Modals; +/// use xous_names::XousNames; +/// let xns = XousNames::new().unwrap(); +/// let modals = Modals::new(&xns).unwrap(); +/// +/// let kbhit = Arc::new(AtomicU32::new(0)); +/// let token = modals.token().clone(); +/// let conn = modals.conn().clone(); +/// let kbhit = kbhit.clone(); +/// // start a keyboard listener +/// kbhit.store(0, Ordering::SeqCst); +/// modals +/// .dynamic_notification(Some("Dynamic Notification Title!"), Some("we'll be listening..")) +/// .unwrap(); +/// let _ = std::thread::spawn({ +/// let token = modals.token().clone(); +/// let conn = modals.conn().clone(); +/// let kbhit = kbhit.clone(); +/// move || { +/// // note that if no key is hit, we get None back on dialog box close automatically +/// match modals::dynamic_notification_blocking_listener(token, conn) { +/// Ok(Some(c)) => { +/// log::trace!("kbhit got {}", c); +/// kbhit.store(c as u32, Ordering::SeqCst) +/// } +/// Ok(None) => { +/// log::trace!("kbhit exited or had no characters"); +/// kbhit.store(0, Ordering::SeqCst) +/// } +/// Err(e) => { +/// log::error!("error waiting for keyboard hit from blocking listener: {:?}", e) +/// } +/// } +/// } +/// }); +/// // load the key hit from kbhit that's obtained from this listener to take dynamic actions while the dialog is active +/// ``` pub fn dynamic_notification_blocking_listener( token: [u32; 4], conn: CID,