From 149beee7b456a7bce0946d7014bc39db4e82be4c Mon Sep 17 00:00:00 2001 From: Alexandre Bury Date: Fri, 4 Oct 2019 13:12:00 -0700 Subject: [PATCH] Add examples to SelectView --- src/align.rs | 20 ++++++ src/cursive.rs | 8 +++ src/views/select_view.rs | 151 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 179 insertions(+) diff --git a/src/align.rs b/src/align.rs index 3291d23..0977679 100644 --- a/src/align.rs +++ b/src/align.rs @@ -25,6 +25,11 @@ impl Align { Align::new(HAlign::Right, VAlign::Top) } + /// Creates a top-center alignment. + pub fn top_center() -> Self { + Align::new(HAlign::Center, VAlign::Top) + } + /// Creates a bottom-left alignment. pub fn bot_left() -> Self { Align::new(HAlign::Left, VAlign::Bottom) @@ -35,6 +40,21 @@ impl Align { Align::new(HAlign::Right, VAlign::Top) } + /// Creates a bottom-center alignment. + pub fn bot_center() -> Self { + Align::new(HAlign::Center, VAlign::Bottom) + } + + /// Creates a center-right alignment. + pub fn center_left() -> Self { + Align::new(HAlign::Left, VAlign::Center) + } + + /// Creates a center-right alignment. + pub fn center_right() -> Self { + Align::new(HAlign::Right, VAlign::Center) + } + /// Creates an alignment centered both horizontally and vertically. pub fn center() -> Self { Align::new(HAlign::Center, VAlign::Center) diff --git a/src/cursive.rs b/src/cursive.rs index 1bbabdd..7799739 100644 --- a/src/cursive.rs +++ b/src/cursive.rs @@ -307,6 +307,14 @@ impl Cursive { /// Callbacks will be executed in the order /// of arrival on the next event cycle. /// + /// # Notes + /// + /// Callbacks need to be `Send`, which can be limiting in some cases. + /// + /// In some case [`send_wrapper`] may help you work around that. + /// + /// [`send_wrapper`]: https://crates.io/crates/send_wrapper + /// /// # Examples /// /// ```rust diff --git a/src/views/select_view.rs b/src/views/select_view.rs index 5e55eef..dac03f7 100644 --- a/src/views/select_view.rs +++ b/src/views/select_view.rs @@ -174,6 +174,31 @@ impl SelectView { /// Sets a callback to be used when an item is selected. /// /// Chainable variant. + /// + /// # Examples + /// + /// ``` + /// use cursive::traits::Identifiable; + /// use cursive::views::{TextView, SelectView}; + /// + /// let text_view = TextView::new("").with_id("text"); + /// + /// let select_view = SelectView::new() + /// .item("One", 1) + /// .item("Two", 2) + /// .on_select(|s, item| { + /// let content = match *item { + /// 1 => "Content number one", + /// 2 => "Content number two! Much better!", + /// _ => unreachable!("no such item"), + /// }; + /// + /// // Update the textview with the currently selected item. + /// s.call_on_id("text", |v: &mut TextView| { + /// v.set_content(content); + /// }).unwrap(); + /// }); + /// ``` pub fn on_select(self, cb: F) -> Self where F: Fn(&mut Cursive, &T) + 'static, @@ -205,6 +230,26 @@ impl SelectView { /// The item currently selected will be given to the callback. /// /// Chainable variant. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::{Dialog, SelectView}; + /// + /// let select_view = SelectView::new() + /// .item("One", 1) + /// .item("Two", 2) + /// .on_submit(|s, item| { + /// let content = match *item { + /// 1 => "Content number one", + /// 2 => "Content number two! Much better!", + /// _ => unreachable!("no such item"), + /// }; + /// + /// // Show a popup whenever the user presses . + /// s.add_layer(Dialog::info(content)); + /// }); + /// ``` pub fn on_submit(self, cb: F) -> Self where F: Fn(&mut Cursive, &V) + 'static, @@ -214,6 +259,17 @@ impl SelectView { } /// Sets the alignment for this view. + /// + /// # Examples + /// + /// ``` + /// use cursive::align; + /// use cursive::views::SelectView; + /// + /// let select_view = SelectView::new() + /// .item("One", 1) + /// .align(align::Align::top_center()); + /// ``` pub fn align(mut self, align: Align) -> Self { self.align = align; @@ -254,6 +310,17 @@ impl SelectView { } /// Adds a item to the list, with given label and value. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::SelectView; + /// + /// let mut select_view = SelectView::new(); + /// + /// select_view.add_item("Item 1", 1); + /// select_view.add_item("Item 2", 2); + /// ``` pub fn add_item>(&mut self, label: S, value: T) { self.items.push(Item::new(label.into(), value)); } @@ -323,6 +390,17 @@ impl SelectView { } /// Chainable variant of add_item + /// + /// # Examples + /// + /// ``` + /// use cursive::views::SelectView; + /// + /// let select_view = SelectView::new() + /// .item("Item 1", 1) + /// .item("Item 2", 2) + /// .item("Surprise item", 42); + /// ``` pub fn item>(self, label: S, value: T) -> Self { self.with(|s| s.add_item(label, value)) } @@ -341,6 +419,18 @@ impl SelectView { /// Adds all items from from an iterator. /// /// Chainable variant. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::SelectView; + /// + /// // Create a SelectView with 100 items + /// let select_view = SelectView::new() + /// .with_all((1u8..100).into_iter().map(|i| { + /// (format!("Item {}", i), i) + /// })); + /// ``` pub fn with_all(self, iter: I) -> Self where S: Into, @@ -372,11 +462,40 @@ impl SelectView { } /// Returns the number of items in this list. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::SelectView; + /// + /// let select_view = SelectView::new() + /// .item("Item 1", 1) + /// .item("Item 2", 2) + /// .item("Item 3", 3); + /// + /// assert_eq!(select_view.len(), 3); + /// ``` pub fn len(&self) -> usize { self.items.len() } /// Returns `true` if this list has no item. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::SelectView; + /// + /// let mut select_view = SelectView::new(); + /// assert!(select_view.is_empty()); + /// + /// select_view.add_item("Item 1", 1); + /// select_view.add_item("Item 2", 2); + /// assert!(!select_view.is_empty()); + /// + /// select_view.clear(); + /// assert!(select_view.is_empty()); + /// ``` pub fn is_empty(&self) -> bool { self.items.is_empty() } @@ -386,8 +505,10 @@ impl SelectView { } /// Sort the current items lexicographically by their label. + /// /// Note that this does not change the current focus index, which means that the current /// selection will likely be changed by the sorting. + /// /// This sort is stable: items with identical label will not be reordered. pub fn sort_by_label(&mut self) { self.items @@ -395,11 +516,15 @@ impl SelectView { } /// Sort the current items with the given comparator function. + /// /// Note that this does not change the current focus index, which means that the current /// selection will likely be changed by the sorting. + /// /// The given comparator function must define a total order for the items. + /// /// If the comparator function does not define a total order, then the order after the sort is /// unspecified. + /// /// This sort is stable: equal items will not be reordered. pub fn sort_by(&mut self, mut compare: F) where @@ -409,8 +534,10 @@ impl SelectView { } /// Sort the current items with the given key extraction function. + /// /// Note that this does not change the current focus index, which means that the current /// selection will likely be changed by the sorting. + /// /// This sort is stable: items with equal keys will not be reordered. pub fn sort_by_key(&mut self, mut key_of: F) where @@ -662,6 +789,17 @@ impl SelectView { } /// Chainable variant of add_item_str + /// + /// # Examples + /// + /// ``` + /// use cursive::views::SelectView; + /// + /// let select_view = SelectView::new() + /// .item_str("Paris") + /// .item_str("New York") + /// .item_str("Tokyo"); + /// ``` pub fn item_str>(self, label: S) -> Self { self.with(|s| s.add_item_str(label)) } @@ -697,6 +835,17 @@ impl SelectView { /// Adds all strings from an iterator. /// /// Chainable variant. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::SelectView; + /// + /// let text = "..."; // Maybe read some config file + /// + /// let select_view = SelectView::new() + /// .with_all_str(text.lines()); + /// ``` pub fn with_all_str(self, iter: I) -> Self where S: Into, @@ -711,8 +860,10 @@ where T: Ord, { /// Sort the current items by their natural ordering. + /// /// Note that this does not change the current focus index, which means that the current /// selection will likely be changed by the sorting. + /// /// This sort is stable: items that are equal will not be reordered. pub fn sort(&mut self) { self.items.sort_by(|a, b| a.value.cmp(&b.value));