Add code examples to the docs of TextBox

AUTHORS

@@ -22,3 +22,4 @@ Tim Murison
 Manmeet Singh
 Simon Fell
 Nick Larsen
+Thomas McAndrew

CHANGELOG.md

@@ -150,6 +150,7 @@ You can find its changes [documented below](#070---2021-01-01).
 - Update docs of `RawLabel`: does not require `ArcStr`([#1886] by [@Maan2003])
 - Fix `Controller` links for `Click` ([#2158] by [@yrns])
 - Delete inaccurate line for `KeyEvent` ([#2247] by [@amtep])
+- Added examples in `TextBox` ([#2284] by [@ThomasMcandrew])
 
 ### Examples
 - Add readme ([#1423] by [@JAicewizard])
@@ -564,6 +565,7 @@ Last release without a changelog :(
 [@NickLarsenNZ]: https://github.com/NickLarsenNZ
 [@barsae]: https://github.com/barsae
 [@amtep]: https://github.com/amtep
+[@ThomasMcandrew]: https:github.com/ThomasMcandrew
 
 [#599]: https://github.com/linebender/druid/pull/599
 [#611]: https://github.com/linebender/druid/pull/611
@@ -862,6 +864,7 @@ Last release without a changelog :(
 [#2203]: https://github.com/linebender/druid/pull/2203
 [#2235]: https://github.com/linebender/druid/pull/2235
 [#2247]: https://github.com/linebender/druid/pull/2247
+[#2284]: https://github.com/linebender/druid/pull/2284
 [Unreleased]: https://github.com/linebender/druid/compare/v0.7.0...master
 [0.7.0]: https://github.com/linebender/druid/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/linebender/druid/compare/v0.5.0...v0.6.0

druid/src/widget/textbox.rs

@@ -78,6 +78,22 @@ pub struct TextBox<T> {
 
 impl<T: EditableText + TextStorage> TextBox<T> {
     /// Create a new TextBox widget.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use druid::widget::TextBox;
+    /// use druid::{ WidgetExt, Data, Lens };
+    ///
+    /// #[derive(Clone, Data, Lens)]
+    /// struct AppState {
+    ///     name: String,
+    /// }
+    ///
+    /// let _ = TextBox::new()
+    ///     .with_placeholder("placeholder text")
+    ///     .lens(AppState::name);
+    /// ```
     pub fn new() -> Self {
         let placeholder_text = ArcStr::from("");
         let mut placeholder_layout = TextLayout::new();
@@ -105,6 +121,20 @@ impl<T: EditableText + TextStorage> TextBox<T> {
     }
 
     /// Create a new multi-line `TextBox`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use druid::widget::TextBox;
+    /// # use druid::{ WidgetExt, Data, Lens };
+    /// #
+    /// # #[derive(Clone, Data, Lens)]
+    /// # struct AppState {
+    /// #     name: String,
+    /// # }
+    /// let multiline = TextBox::multiline()
+    ///     .lens(AppState::name);
+    /// ```
     pub fn multiline() -> Self {
         let mut this = TextBox::new();
         this.inner
@@ -121,6 +151,37 @@ impl<T: EditableText + TextStorage> TextBox<T> {
     /// If `false`, lines will not be wrapped, and horizontal scrolling will
     /// be enabled.
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use druid::widget::TextBox;
+    /// # use druid::{ WidgetExt, Data, Lens };
+    /// #
+    /// # #[derive(Clone, Data, Lens)]
+    /// # struct AppState {
+    /// #     name: String,
+    /// # }
+    /// //will scroll horizontally
+    /// let scroll_text_box = TextBox::new()
+    ///     .with_line_wrapping(false)
+    ///     .lens(AppState::name);
+    ///
+    /// //will wrap only for a single line
+    /// let wrap_text_box = TextBox::new()
+    ///     .with_line_wrapping(true)
+    ///     .lens(AppState::name);
+    ///
+    /// //will scroll as well as having multiple lines
+    /// let scroll_multi_line_text_box = TextBox::multiline()
+    ///     .with_line_wrapping(false)
+    ///     .lens(AppState::name);
+    ///
+    /// //will wrap for each line
+    /// let wrap_multi_line_text_box = TextBox::multiline()
+    ///     .with_line_wrapping(true) // this is default and can be removed for the same result
+    ///     .lens(AppState::name);
+    ///
+    /// ```
     /// [`multiline`]: TextBox::multiline
     pub fn with_line_wrapping(mut self, wrap_lines: bool) -> Self {
         self.inner.set_horizontal_scroll_enabled(!wrap_lines);
@@ -133,6 +194,37 @@ impl<T> TextBox<T> {
     ///
     /// The argument can be either an `f64` or a [`Key<f64>`].
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use druid::widget::TextBox;
+    /// # use druid::{ WidgetExt, Data, Lens };
+    /// #
+    /// # #[derive(Clone, Data, Lens)]
+    /// # struct AppState {
+    /// #     name: String,
+    /// # }
+    /// let text_box = TextBox::new()
+    ///     .with_text_size(14.)
+    ///     .lens(AppState::name);
+    /// ```
+    ///
+    /// ```
+    /// # use druid::widget::TextBox;
+    /// # use druid::{ WidgetExt, Data, Lens };
+    /// #
+    /// # #[derive(Clone, Data, Lens)]
+    /// # struct AppState {
+    /// #     name: String,
+    /// # }
+    /// use druid::Key;
+    ///
+    /// const FONT_SIZE : Key<f64> = Key::new("font-size");
+    ///
+    /// let text_box = TextBox::new()
+    ///     .with_text_size(FONT_SIZE)
+    ///     .lens(AppState::name);
+    /// ```
     /// [`Key<f64>`]: ../struct.Key.html
     pub fn with_text_size(mut self, size: impl Into<KeyOrValue<f64>>) -> Self {
         self.set_text_size(size);
@@ -155,6 +247,22 @@ impl<T> TextBox<T> {
     /// This should be considered a bug, but it will not be fixed until proper
     /// BiDi support is implemented.
     ///
+    /// # Examples
+    /// ```
+    /// # use druid::widget::TextBox;
+    /// # use druid::{ WidgetExt, Data, Lens };
+    /// #
+    /// # #[derive(Clone, Data, Lens)]
+    /// # struct AppState {
+    /// #     name: String,
+    /// # }
+    /// use druid::TextAlignment;
+    ///
+    /// let text_box = TextBox::new()
+    ///     .with_text_alignment(TextAlignment::Center)
+    ///     .lens(AppState::name);
+    /// ```
+    ///
     /// [`TextAlignment`]: enum.TextAlignment.html
     /// [`multiline`]: #method.multiline
     pub fn with_text_alignment(mut self, alignment: TextAlignment) -> Self {
@@ -167,6 +275,30 @@ impl<T> TextBox<T> {
     /// The argument can be a [`FontDescriptor`] or a [`Key<FontDescriptor>`]
     /// that refers to a font defined in the [`Env`].
     ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use druid::widget::TextBox;
+    /// # use druid::{ WidgetExt, Data, Lens };
+    /// #
+    /// # #[derive(Clone, Data, Lens)]
+    /// # struct AppState {
+    /// #     name: String,
+    /// # }
+    /// use druid::{ FontDescriptor, FontFamily, Key };
+    ///
+    /// const FONT : Key<FontDescriptor> = Key::new("font");
+    ///
+    /// let text_box = TextBox::new()
+    ///     .with_font(FontDescriptor::new(FontFamily::MONOSPACE))
+    ///     .lens(AppState::name);
+    ///
+    /// let text_box = TextBox::new()
+    ///     .with_font(FONT)
+    ///     .lens(AppState::name);
+    /// ```
+    ///
+    ///
     /// [`Env`]: ../struct.Env.html
     /// [`FontDescriptor`]: ../struct.FontDescriptor.html
     /// [`Key<FontDescriptor>`]: ../struct.Key.html
@@ -178,7 +310,27 @@ impl<T> TextBox<T> {
     /// Builder-style method for setting the text color.
     ///
     /// The argument can be either a `Color` or a [`Key<Color>`].
+    /// # Examples
+    /// ```
+    /// # use druid::widget::TextBox;
+    /// # use druid::{ WidgetExt, Data, Lens };
+    /// #
+    /// # #[derive(Clone, Data, Lens)]
+    /// # struct AppState {
+    /// #     name: String,
+    /// # }
+    /// use druid::{ Color, Key };
+    ///
+    /// const COLOR : Key<Color> = Key::new("color");
+    ///
+    /// let text_box = TextBox::new()
+    ///     .with_text_color(Color::RED)
+    ///     .lens(AppState::name);
     ///
+    /// let text_box = TextBox::new()
+    ///     .with_text_color(COLOR)
+    ///     .lens(AppState::name);
+    /// ```
     /// [`Key<Color>`]: ../struct.Key.html
     pub fn with_text_color(mut self, color: impl Into<KeyOrValue<Color>>) -> Self {
         self.set_text_color(color);