Skip to content

Commit

Permalink
updating docs to use Selector.with instead of Command::new (#1761)
Browse files Browse the repository at this point in the history 
- adding some more explanation for Target::Auto
- updating doc links to use new doc links
  • Loading branch information
@arthmis
arthmis authored May 6, 2021
1 parent 03800f1 commit def6ea1
Show file tree
Hide file tree
Showing 6 changed files with 39 additions and 49 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
12 changes: 2 additions & 10 deletions druid/examples/open_save.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
29 changes: 13 additions & 16 deletions druid/src/command.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]));
/// ```
Expand Down Expand Up @@ -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() {
Expand All @@ -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,
}

Expand Down Expand Up @@ -382,11 +387,7 @@ 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.
///
/// [`Command::new`]: struct.Command.html#method.new
/// [`Command::to`]: struct.Command.html#method.to
/// [`Target::Auto`]: enum.Target.html#variant.Auto
/// The [`Selector::to`] method can be used to override this.
pub fn with(self, payload: T) -> Command {
Command::new(self, payload, Target::Auto)
}
Expand All @@ -395,13 +396,9 @@ 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>`.
///
/// [`Selector`]: struct.Selector.html
/// [`Selector::with`]: struct.Selector.html#method.with
/// [`Target`]: enum.Target.html
pub fn new<T: Any>(selector: Selector<T>, payload: T, target: impl Into<Target>) -> Self {
Command {
symbol: selector.symbol(),
Expand Down Expand Up @@ -655,7 +652,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]));
}

Expand Down
2 changes: 1 addition & 1 deletion druid/src/core.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
}
Expand Down
14 changes: 6 additions & 8 deletions druid/src/sub_window.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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),
)
}
}
}
Expand Down
28 changes: 14 additions & 14 deletions druid/src/tests/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]);
})
Expand Down Expand Up @@ -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);
})
Expand Down Expand Up @@ -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();
Expand Down

0 comments on commit def6ea1

Please sign in to comment.