diff --git a/AUTHORS b/AUTHORS index d22772a73c..41bdaf7103 100644 --- a/AUTHORS +++ b/AUTHORS @@ -22,3 +22,4 @@ Tim Murison Manmeet Singh Simon Fell Nick Larsen +Thomas McAndrew diff --git a/CHANGELOG.md b/CHANGELOG.md index 536c8979ed..9166511187 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/druid/src/widget/textbox.rs b/druid/src/widget/textbox.rs index c525f43e7d..abccd1d616 100644 --- a/druid/src/widget/textbox.rs +++ b/druid/src/widget/textbox.rs @@ -78,6 +78,22 @@ pub struct TextBox { impl TextBox { /// 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 TextBox { } /// 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 TextBox { /// 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 TextBox { /// /// The argument can be either an `f64` or a [`Key`]. /// + /// # 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 = Key::new("font-size"); + /// + /// let text_box = TextBox::new() + /// .with_text_size(FONT_SIZE) + /// .lens(AppState::name); + /// ``` /// [`Key`]: ../struct.Key.html pub fn with_text_size(mut self, size: impl Into>) -> Self { self.set_text_size(size); @@ -155,6 +247,22 @@ impl TextBox { /// 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 TextBox { /// The argument can be a [`FontDescriptor`] or a [`Key`] /// 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 = 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`]: ../struct.Key.html @@ -178,7 +310,27 @@ impl TextBox { /// Builder-style method for setting the text color. /// /// The argument can be either a `Color` or a [`Key`]. + /// # 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 = 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`]: ../struct.Key.html pub fn with_text_color(mut self, color: impl Into>) -> Self { self.set_text_color(color);