Add more examples

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<T: View> {
     /// Constraint on each axis
     size: XY<SizeConstraint>,

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<F, S: Into<String>>(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<S>(&mut self, label: S)
     where
         S: Into<String>,

src/views/canvas.rs

@@ -12,6 +12,40 @@ type CallOnAny<T> = Box<dyn for<'a> 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<T> {
     state: T,
 
@@ -46,16 +80,6 @@ impl<T: 'static + View> Canvas<T> {
 
 impl<T> Canvas<T> {
     /// 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,

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
     }

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<V: View + 'static>(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<S: Into<String>>(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<S: Into<String>>(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<S: Into<String>>(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<S: Into<String>>(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<T: Into<Margins>>(mut self, padding: T) -> Self {
         self.padding = padding.into();
 

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<F>(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 `<Enter>` 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<F>(self, callback: F) -> Self
     where
         F: Fn(&mut Cursive, &str) + 'static,

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<Checkbox>| {
+///             // This will disable (or re-enable) the checkbox, preventing the user from
+///             // interacting with it.
+///             v.set_enabled(!v.is_enabled());
+///         });
+///     }))
+/// );
+/// ```
 pub struct EnableableView<V> {
     view: V,
     enabled: bool,

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<V: View> {
     view: Rc<RefCell<V>>,
     id: String,

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)]

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<Child>,
     orientation: direction::Orientation,

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<MenuTree>,
     focus: usize,

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<S>(&mut self, content: S)
+    pub fn set_content<S>(&self, content: S)
     where
         S: Into<StyledString>,
     {
@@ -94,7 +94,7 @@ impl TextContent {
     }
 
     /// Append `content` to the end of a `TextView`.
-    pub fn append<S>(&mut self, content: S)
+    pub fn append<S>(&self, content: S)
     where
         S: Into<StyledString>,
     {
@@ -113,7 +113,8 @@ impl TextContent {
         TextContentInner::get_content(&self.content)
     }
 
-    fn with_content<F, O>(&mut self, f: F) -> O
+    /// Apply the given closure to the inner content, and bust the cache afterward.
+    fn with_content<F, O>(&self, f: F) -> O
     where
         F: FnOnce(&mut TextContentInner) -> O,
     {