From 5bf6f952d1fda6646e412c39b41d8ad3d30c8e85 Mon Sep 17 00:00:00 2001 From: Alexandre Bury Date: Mon, 7 Oct 2019 16:14:35 -0700 Subject: [PATCH] Add more examples --- src/views/box_view.rs | 5 +++- src/views/button.rs | 20 +++++++++++++- src/views/canvas.rs | 44 +++++++++++++++++++++++------- src/views/checkbox.rs | 21 ++++++++++++++ src/views/dialog.rs | 53 ++++++++++++++++++++++++++++++++++++ src/views/edit_view.rs | 25 +++++++++++++++++ src/views/enableable_view.rs | 21 ++++++++++++++ src/views/id_view.rs | 6 +++- src/views/layer.rs | 2 +- src/views/linear_layout.rs | 12 ++++++++ src/views/menu_popup.rs | 6 ++++ src/views/text_view.rs | 7 +++-- 12 files changed, 205 insertions(+), 17 deletions(-) diff --git a/src/views/box_view.rs b/src/views/box_view.rs index 4ff76bd..9f7bc88 100644 --- a/src/views/box_view.rs +++ b/src/views/box_view.rs @@ -16,10 +16,13 @@ use crate::XY; /// # Examples /// /// ``` -/// # use cursive::views::{BoxView,TextView}; +/// use cursive::views::{BoxView, TextView}; +/// /// // Creates a 20x4 BoxView with a TextView content. /// let view = BoxView::with_fixed_size((20,4), TextView::new("Hello!")); /// ``` +/// +/// See also [`Boxable`](crate::view::Boxable) for an easy way to wrap any view. pub struct BoxView { /// Constraint on each axis size: XY, diff --git a/src/views/button.rs b/src/views/button.rs index db72bb0..0d1bcb0 100644 --- a/src/views/button.rs +++ b/src/views/button.rs @@ -15,7 +15,8 @@ use unicode_width::UnicodeWidthStr; /// # Examples /// /// ``` -/// # use cursive::views::Button; +/// use cursive::views::Button; +/// /// let quit_button = Button::new("Quit", |s| s.quit()); /// ``` pub struct Button { @@ -39,6 +40,14 @@ impl Button { } /// Creates a new button without angle brackets. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::Button; + /// + /// let button = Button::new_raw("[ Quit ]", |s| s.quit()); + /// ``` pub fn new_raw>(label: S, cb: F) -> Self where F: 'static + Fn(&mut Cursive), @@ -109,6 +118,15 @@ impl Button { /// Sets the label to the given value. /// /// This will include brackets. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::Button; + /// + /// let mut button = Button::new("Quit", |s| s.quit()); + /// button.set_label("Escape"); + /// ``` pub fn set_label(&mut self, label: S) where S: Into, diff --git a/src/views/canvas.rs b/src/views/canvas.rs index f7ded06..e0a8567 100644 --- a/src/views/canvas.rs +++ b/src/views/canvas.rs @@ -12,6 +12,40 @@ type CallOnAny = Box FnMut(&mut T, &Selector, AnyCb<'a>)>; /// A blank view that forwards calls to closures. /// /// You can use this view to easily draw your own interface. +/// +/// # Examples +/// +/// ```rust +/// use cursive::views::{Canvas, Dialog}; +/// use cursive::event::{Event, EventResult, Key}; +/// use unicode_width::UnicodeWidthStr; // To get the width of some text. +/// +/// // Build a canvas around a string. +/// let state = String::new(); +/// let canvas = Canvas::new(state) +/// .with_draw(|text: &String, printer| { +/// // Simply print our string +/// printer.print((0,0), text); +/// }) +/// .with_on_event(|text: &mut String, event| { +/// match event { +/// Event::Char(c) => { +/// text.push(c); +/// EventResult::Consumed(None) +/// } +/// Event::Key(Key::Enter) => { +/// let text = text.clone(); +/// EventResult::with_cb(move |s| { +/// s.add_layer(Dialog::info(&text)); +/// }) +/// }, +/// _ => EventResult::Ignored, +/// } +/// }) +/// .with_required_size(|text, _constraints| { +/// (text.width(), 1).into() +/// }); +/// ``` pub struct Canvas { state: T, @@ -46,16 +80,6 @@ impl Canvas { impl Canvas { /// Creates a new, empty Canvas. - /// - /// # Examples - /// - /// ```rust - /// # use cursive::views::Canvas; - /// let canvas = Canvas::new(()) - /// .with_draw(|printer, _| { - /// // Print the view - /// }); - /// ``` pub fn new(state: T) -> Self { Canvas { state, diff --git a/src/views/checkbox.rs b/src/views/checkbox.rs index b66848b..dd99053 100644 --- a/src/views/checkbox.rs +++ b/src/views/checkbox.rs @@ -9,6 +9,15 @@ use crate::With; use std::rc::Rc; /// Checkable box. +/// +/// # Examples +/// +/// ``` +/// use cursive::views::Checkbox; +/// use cursive::traits::Identifiable; +/// +/// let checkbox = Checkbox::new().checked().with_id("check"); +/// ``` pub struct Checkbox { checked: bool, enabled: bool, @@ -69,6 +78,18 @@ impl Checkbox { } /// Returns `true` if the checkbox is checked. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::Checkbox; + /// + /// let mut checkbox = Checkbox::new().checked(); + /// assert!(checkbox.is_checked()); + /// + /// checkbox.uncheck(); + /// assert!(!checkbox.is_checked()); + /// ``` pub fn is_checked(&self) -> bool { self.checked } diff --git a/src/views/dialog.rs b/src/views/dialog.rs index 8c74d16..8e76b38 100644 --- a/src/views/dialog.rs +++ b/src/views/dialog.rs @@ -108,6 +108,16 @@ impl Dialog { /// Sets the content for this dialog. /// /// Chainable variant. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::{Dialog, TextView}; + /// + /// let dialog = Dialog::new() + /// .content(TextView::new("Hello!")) + /// .button("Quit", |s| s.quit()); + /// ``` pub fn content(self, view: V) -> Self { self.with(|s| s.set_content(view)) } @@ -143,6 +153,15 @@ impl Dialog { } /// Convenient method to create a dialog with a simple text content. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::Dialog; + /// + /// let dialog = Dialog::text("Hello!") + /// .button("Quit", |s| s.quit()); + /// ``` pub fn text>(text: S) -> Self { Self::around(TextView::new(text)) } @@ -150,6 +169,14 @@ impl Dialog { /// Convenient method to create an infobox. /// /// It will contain the given text and a `Ok` dismiss button. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::Dialog; + /// + /// let dialog = Dialog::info("Some very important information!"); + /// ``` pub fn info>(text: S) -> Self { Dialog::text(text).dismiss_button("Ok") } @@ -217,6 +244,15 @@ impl Dialog { */ /// Shortcut method to add a button that will dismiss the dialog. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::Dialog; + /// + /// let dialog = Dialog::text("Hello!") + /// .dismiss_button("Close"); + /// ``` pub fn dismiss_button>(self, label: S) -> Self { self.button(label, |s| { s.pop_layer(); @@ -226,6 +262,15 @@ impl Dialog { /// Sets the title of the dialog. /// /// If not empty, it will be visible at the top. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::Dialog; + /// + /// let dialog = Dialog::info("Some info") + /// .title("Read me!"); + /// ``` pub fn title>(self, label: S) -> Self { self.with(|s| s.set_title(label)) } @@ -249,6 +294,14 @@ impl Dialog { } /// Sets the padding in the dialog (around content and buttons). + /// + /// # Examples + /// ``` + /// use cursive::views::Dialog; + /// + /// let dialog = Dialog::info("Hello!") + /// .padding(((1, 1), (0, 0))); // ((Left, Right), (Top, Bottom)) + /// ``` pub fn padding>(mut self, padding: T) -> Self { self.padding = padding.into(); diff --git a/src/views/edit_view.rs b/src/views/edit_view.rs index 6d037fd..d42b619 100644 --- a/src/views/edit_view.rs +++ b/src/views/edit_view.rs @@ -268,6 +268,20 @@ impl EditView { /// Sets a callback to be called whenever the content is modified. /// /// Chainable variant. See [`set_on_edit`](#method.set_on_edit). + /// + /// # Examples + /// + /// ``` + /// use cursive::views::{TextContent, TextView, EditView}; + /// // Keep the length of the text in a separate view. + /// let mut content = TextContent::new("0"); + /// let text_view = TextView::new_with_content(content.clone()); + /// + /// let on_edit = EditView::new() + /// .on_edit(move |_s, text, _cursor| { + /// content.set_content(format!("{}", text.len())); + /// }); + /// ``` pub fn on_edit(self, callback: F) -> Self where F: Fn(&mut Cursive, &str, usize) + 'static, @@ -328,6 +342,17 @@ impl EditView { /// Sets a callback to be called when `` is pressed. /// /// Chainable variant. + /// + /// # Examples + /// + /// ``` + /// use cursive::views::{Dialog, EditView}; + /// + /// let edit_view = EditView::new() + /// .on_submit(|s, text| { + /// s.add_layer(Dialog::info(text)); + /// }); + /// ``` pub fn on_submit(self, callback: F) -> Self where F: Fn(&mut Cursive, &str) + 'static, diff --git a/src/views/enableable_view.rs b/src/views/enableable_view.rs index 676d67f..17254d1 100644 --- a/src/views/enableable_view.rs +++ b/src/views/enableable_view.rs @@ -5,6 +5,27 @@ use crate::{Printer, With}; /// Wrapper around another view that can be enabled/disabled at will. /// /// When disabled, all child views will be disabled and will stop receiving events. +/// +/// # Examples +/// +/// ``` +/// use cursive::Cursive; +/// use cursive::views::{Button, EnableableView, Checkbox, LinearLayout}; +/// use cursive::traits::Identifiable; +/// +/// let mut siv = Cursive::dummy(); +/// +/// siv.add_layer(LinearLayout::vertical() +/// .child(EnableableView::new(Checkbox::new()).with_id("my_view")) +/// .child(Button::new("Toggle", |s| { +/// s.call_on_id("my_view", |v: &mut EnableableView| { +/// // This will disable (or re-enable) the checkbox, preventing the user from +/// // interacting with it. +/// v.set_enabled(!v.is_enabled()); +/// }); +/// })) +/// ); +/// ``` pub struct EnableableView { view: V, enabled: bool, diff --git a/src/views/id_view.rs b/src/views/id_view.rs index 43e2c52..91b82d9 100644 --- a/src/views/id_view.rs +++ b/src/views/id_view.rs @@ -5,7 +5,11 @@ use std::cell::{RefCell, RefMut}; use std::ops::DerefMut; use std::rc::Rc; -/// Wrapper around a view to provide interior mutability. +/// Wrapper around a view to make it identifiable. +/// +/// This lets other views refer to this one using a string identifier. +/// +/// See [`Identifiable`](crate::view::Identifiable) for an easy way to wrap any view with it. pub struct IdView { view: Rc>, id: String, diff --git a/src/views/layer.rs b/src/views/layer.rs index a9af8e0..9ce87df 100644 --- a/src/views/layer.rs +++ b/src/views/layer.rs @@ -3,7 +3,7 @@ use crate::Printer; /// Wrapper view that fills the background. /// -/// Used as layer in the [`StackView`]. +/// This is mostly used as layer in the [`StackView`]. /// /// [`StackView`]: struct.StackView.html #[derive(Debug)] diff --git a/src/views/linear_layout.rs b/src/views/linear_layout.rs index afcb44b..7cc2ab0 100644 --- a/src/views/linear_layout.rs +++ b/src/views/linear_layout.rs @@ -11,6 +11,18 @@ use std::cmp::min; use std::ops::Deref; /// Arranges its children linearly according to its orientation. +/// +/// # Examples +/// +/// ``` +/// use cursive::views::{Button, LinearLayout, TextView, TextArea}; +/// use cursive::traits::Boxable; +/// +/// let linear_layout = LinearLayout::horizontal() +/// .child(TextView::new("Top of the page")) +/// .child(TextArea::new().fixed_size((20, 5))) +/// .child(Button::new("Ok", |s| s.quit())); +/// ``` pub struct LinearLayout { children: Vec, orientation: direction::Orientation, diff --git a/src/views/menu_popup.rs b/src/views/menu_popup.rs index cece4b6..672547c 100644 --- a/src/views/menu_popup.rs +++ b/src/views/menu_popup.rs @@ -16,6 +16,12 @@ use std::rc::Rc; use unicode_width::UnicodeWidthStr; /// Popup that shows a list of items. +/// +/// This is mostly used indirectly when creating a [popup `SelectView`][1] or +/// a [menubar][2]. +/// +/// [1]: crate::views::SelectView::popup() +/// [2]: crate::Cursive::menubar() pub struct MenuPopup { menu: Rc, focus: usize, diff --git a/src/views/text_view.rs b/src/views/text_view.rs index d017aa9..5872b16 100644 --- a/src/views/text_view.rs +++ b/src/views/text_view.rs @@ -84,7 +84,7 @@ impl Deref for TextContentRef { impl TextContent { /// Replaces the content with the given value. - pub fn set_content(&mut self, content: S) + pub fn set_content(&self, content: S) where S: Into, { @@ -94,7 +94,7 @@ impl TextContent { } /// Append `content` to the end of a `TextView`. - pub fn append(&mut self, content: S) + pub fn append(&self, content: S) where S: Into, { @@ -113,7 +113,8 @@ impl TextContent { TextContentInner::get_content(&self.content) } - fn with_content(&mut self, f: F) -> O + /// Apply the given closure to the inner content, and bust the cache afterward. + fn with_content(&self, f: F) -> O where F: FnOnce(&mut TextContentInner) -> O, {