updating docs to use Selector.with instead of Command::new

CHANGELOG.md

@@ -82,6 +82,8 @@ You can find its changes [documented below](#070---2021-01-01).
 - Added missing documentation on derived lens items ([#1696] by [@lidin])
 - Fix example code in `Get started with Druid` chapter of book ([#1698] by [@ccqpein])
 - Fix link in documentation of widget::Image ([#1730] by [@RichardPoole42])
+- Added more detailed explanation of `Target::Auto` ([#1761] by [@arthmis])
+- Updated source code, tests and docs to use `Selector::with` instead of `Command::new` ([#1761] by [@arthmis])
 
 ### Examples
 
@@ -712,6 +714,7 @@ Last release without a changelog :(
 [#1754]: https://github.com/linebender/druid/pull/1754
 [#1755]: https://github.com/linebender/druid/pull/1755
 [#1756]: https://github.com/linebender/druid/pull/1756
+[#1761]: https://github.com/linebender/druid/pull/1761
 
 [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

druid/examples/open_save.rs

@@ -56,18 +56,10 @@ fn ui_builder() -> impl Widget<String> {
 
     let input = TextBox::new();
     let save = Button::new("Save").on_click(move |ctx, _, _| {
-        ctx.submit_command(Command::new(
-            druid::commands::SHOW_SAVE_PANEL,
-            save_dialog_options.clone(),
-            Target::Auto,
-        ))
+        ctx.submit_command(druid::commands::SHOW_SAVE_PANEL.with(save_dialog_options.clone()))
     });
     let open = Button::new("Open").on_click(move |ctx, _, _| {
-        ctx.submit_command(Command::new(
-            druid::commands::SHOW_OPEN_PANEL,
-            open_dialog_options.clone(),
-            Target::Auto,
-        ))
+        ctx.submit_command(druid::commands::SHOW_SAVE_PANEL.with(open_dialog_options.clone()))
     });
 
     let mut col = Flex::column();

druid/src/command.rs

@@ -77,7 +77,7 @@ pub struct Selector<T = ()>(SelectorSymbol, PhantomData<T>);
 ///
 /// let selector = Selector::new("process_rows");
 /// let rows = vec![1, 3, 10, 12];
-/// let command = Command::new(selector, rows, Target::Auto);
+/// let command = selector.with(rows);
 ///
 /// assert_eq!(command.get(selector), Some(&vec![1, 3, 10, 12]));
 /// ```
@@ -129,7 +129,7 @@ pub struct Notification {
 ///
 /// let selector = Selector::new("use-once");
 /// let num = CantClone(42);
-/// let command = Command::new(selector, SingleUse::new(num), Target::Auto);
+/// let command = selector.with(SingleUse::new(num));
 ///
 /// let payload: &SingleUse<CantClone> = command.get_unchecked(selector);
 /// if let Some(num) = payload.take() {
@@ -154,21 +154,26 @@ pub enum Target {
     /// The `Command` will be delivered to all open windows, and all widgets
     /// in each window. Delivery will stop if the event is [`handled`].
     ///
-    /// [`handled`]: struct.EventCtx.html#set_handled
+    /// [`handled`]: crate::EventCtx::set_handled
     Global,
     /// The target is a specific window.
     ///
     /// The `Command` will be delivered to all widgets in that window.
     /// Delivery will stop if the event is [`handled`].
     ///
-    /// [`handled`]: struct.EventCtx.html#set_handled
+    /// [`handled`]: crate::EventCtx::set_handled
     Window(WindowId),
     /// The target is a specific widget.
     Widget(WidgetId),
     /// The target will be determined automatically.
     ///
     /// How this behaves depends on the context used to submit the command.
-    /// Each `submit_command` function should have documentation about the specific behavior.
+    /// If the command is submitted within a `Widget` method, then it will be sent to the host
+    /// window for that widget. If it is from outside the application, via [`ExtEventSink`],
+    /// or from the root [`AppDelegate`] then it will be sent to [`Target::Global`] .
+    ///
+    /// [`ExtEventSink`]: crate::ExtEventSink
+    /// [`AppDelegate`]: crate::AppDelegate
     Auto,
 }
 
@@ -382,11 +387,11 @@ impl<T: Any> Selector<T> {
     /// as `Selector<()>` implements `Into<Command>`.
     ///
     /// By default, the command will have [`Target::Auto`].
-    /// The [`Command::to`] method can be used to override this.
+    /// The [`Selector::to`] method can be used to override this.
     ///
-    /// [`Command::new`]: struct.Command.html#method.new
-    /// [`Command::to`]: struct.Command.html#method.to
-    /// [`Target::Auto`]: enum.Target.html#variant.Auto
+    /// [`Command::new`]: Command::new
+    /// [`Selector::to`]: Selector::to
+    /// [`Target::Auto`]: Target::Auto
     pub fn with(self, payload: T) -> Command {
         Command::new(self, payload, Target::Auto)
     }
@@ -395,7 +400,7 @@ impl<T: Any> Selector<T> {
 impl Command {
     /// Create a new `Command` with a payload and a [`Target`].
     ///
-    /// [`Selector::with`] can be used to create `Command`s more conveniently.
+    /// [`Selector::with`] should be used to create `Command`s more conveniently.
     ///
     /// If you do not need a payload, [`Selector`] implements `Into<Command>`.
     ///
@@ -655,7 +660,7 @@ mod tests {
     fn get_payload() {
         let sel = Selector::new("my-selector");
         let payload = vec![0, 1, 2];
-        let command = Command::new(sel, payload, Target::Auto);
+        let command = sel.with(payload);
         assert_eq!(command.get(sel), Some(&vec![0, 1, 2]));
     }
 

druid/src/core.rs

@@ -1151,7 +1151,7 @@ impl<T: Data, W: Widget<T>> WidgetPod<T, W> {
                         None
                     },
                 };
-                let command = Command::new(SUB_WINDOW_PARENT_TO_HOST, update, *host);
+                let command = SUB_WINDOW_PARENT_TO_HOST.with(update).to(*host);
                 ctx.submit_command(command);
             }
         }

druid/src/sub_window.rs

@@ -17,9 +17,7 @@ use crate::commands::{SUB_WINDOW_HOST_TO_PARENT, SUB_WINDOW_PARENT_TO_HOST};
 use crate::lens::Unit;
 use crate::widget::prelude::*;
 use crate::win_handler::AppState;
-use crate::{
-    Command, Data, Point, Rect, Widget, WidgetExt, WidgetId, WidgetPod, WindowHandle, WindowId,
-};
+use crate::{Data, Point, Rect, Widget, WidgetExt, WidgetId, WidgetPod, WindowHandle, WindowId};
 use druid_shell::Error;
 use std::any::Any;
 use std::ops::Deref;
@@ -126,11 +124,11 @@ impl<U: Data, W: Widget<U>> Widget<()> for SubWindowHost<U, W> {
                 let old = self.data.clone(); // Could avoid this by keeping two bit of data or if we could ask widget pod?
                 self.child.event(ctx, event, &mut self.data, &self.env);
                 if !old.same(&self.data) {
-                    ctx.submit_command(Command::new(
-                        SUB_WINDOW_HOST_TO_PARENT,
-                        Box::new(self.data.clone()),
-                        self.parent_id,
-                    ))
+                    ctx.submit_command(
+                        SUB_WINDOW_HOST_TO_PARENT
+                            .with(Box::new(self.data.clone()))
+                            .to(self.parent_id),
+                    )
                 }
             }
         }

druid/src/tests/mod.rs

@@ -419,23 +419,23 @@ fn simple_disable() {
         harness.send_initial_events();
         check_states("send_initial_events", [None, None, None, None]);
         assert_eq!(harness.window().focus_chain(), &[id_0, id_1, id_2, id_3]);
-        harness.submit_command(Command::new(CHANGE_DISABLED, true, id_0));
+        harness.submit_command(CHANGE_DISABLED.with(true).to(id_0));
         check_states("Change 1", [Some(true), None, None, None]);
         assert_eq!(harness.window().focus_chain(), &[id_1, id_2, id_3]);
-        harness.submit_command(Command::new(CHANGE_DISABLED, true, id_2));
+        harness.submit_command(CHANGE_DISABLED.with(true).to(id_2));
         check_states("Change 2", [Some(true), None, Some(true), None]);
         assert_eq!(harness.window().focus_chain(), &[id_1, id_3]);
-        harness.submit_command(Command::new(CHANGE_DISABLED, true, id_3));
+        harness.submit_command(CHANGE_DISABLED.with(true).to(id_3));
         check_states("Change 3", [Some(true), None, Some(true), Some(true)]);
         assert_eq!(harness.window().focus_chain(), &[id_1]);
-        harness.submit_command(Command::new(CHANGE_DISABLED, false, id_2));
+        harness.submit_command(CHANGE_DISABLED.with(false).to(id_2));
         check_states("Change 4", [Some(true), None, Some(false), Some(true)]);
         assert_eq!(harness.window().focus_chain(), &[id_1, id_2]);
-        harness.submit_command(Command::new(CHANGE_DISABLED, true, id_2));
+        harness.submit_command(CHANGE_DISABLED.with(true).to(id_2));
         check_states("Change 5", [Some(true), None, Some(true), Some(true)]);
         assert_eq!(harness.window().focus_chain(), &[id_1]);
         //This is intended the widget should not receive an event!
-        harness.submit_command(Command::new(CHANGE_DISABLED, false, id_1));
+        harness.submit_command(CHANGE_DISABLED.with(false).to(id_1));
         check_states("Change 6", [Some(true), None, Some(true), Some(true)]);
         assert_eq!(harness.window().focus_chain(), &[id_1]);
     })
@@ -493,25 +493,25 @@ fn resign_focus_on_disable() {
         harness.send_initial_events();
         assert_eq!(harness.window().focus_chain(), &[id_0, id_1, id_2]);
         assert_eq!(harness.window().focus, None);
-        harness.submit_command(Command::new(REQUEST_FOCUS, (), id_2));
+        harness.submit_command(REQUEST_FOCUS.to(id_2));
         assert_eq!(harness.window().focus_chain(), &[id_0, id_1, id_2]);
         assert_eq!(harness.window().focus, Some(id_2));
-        harness.submit_command(Command::new(CHANGE_DISABLED, true, id_0));
+        harness.submit_command(CHANGE_DISABLED.with(true).to(id_0));
         assert_eq!(harness.window().focus_chain(), &[id_2]);
         assert_eq!(harness.window().focus, Some(id_2));
-        harness.submit_command(Command::new(CHANGE_DISABLED, true, id_2));
+        harness.submit_command(CHANGE_DISABLED.with(true).to(id_2));
         assert_eq!(harness.window().focus_chain(), &[]);
         assert_eq!(harness.window().focus, None);
-        harness.submit_command(Command::new(CHANGE_DISABLED, false, id_0));
+        harness.submit_command(CHANGE_DISABLED.with(false).to(id_0));
         assert_eq!(harness.window().focus_chain(), &[id_0, id_1]);
         assert_eq!(harness.window().focus, None);
-        harness.submit_command(Command::new(REQUEST_FOCUS, (), id_1));
+        harness.submit_command(REQUEST_FOCUS.to(id_1));
         assert_eq!(harness.window().focus_chain(), &[id_0, id_1]);
         assert_eq!(harness.window().focus, Some(id_1));
-        harness.submit_command(Command::new(CHANGE_DISABLED, false, id_2));
+        harness.submit_command(CHANGE_DISABLED.with(false).to(id_2));
         assert_eq!(harness.window().focus_chain(), &[id_0, id_1, id_2]);
         assert_eq!(harness.window().focus, Some(id_1));
-        harness.submit_command(Command::new(CHANGE_DISABLED, true, id_0));
+        harness.submit_command(CHANGE_DISABLED.with(true).to(id_0));
         assert_eq!(harness.window().focus_chain(), &[id_2]);
         assert_eq!(harness.window().focus, None);
     })
@@ -555,7 +555,7 @@ fn disable_tree() {
 
     fn multi_update(states: &[(WidgetId, bool)]) -> Command {
         let payload = states.iter().cloned().collect::<HashMap<_, _>>();
-        Command::new(MULTI_CHANGE_DISABLED, payload, Target::Global)
+        MULTI_CHANGE_DISABLED.with(payload).to(Target::Global)
     }
 
     let disabled_0: Rc<Cell<Option<bool>>> = Default::default();