Rename Pointer<Down/Up> -> Pointer<Pressed/Released> in bevy_picking.

[harun-ibram]

Objective

Fixes #16192

Solution

I renamed the Pointer<Down/Up> to <Pressed/Released> and then I resolved all the errors. Renamed variables like "is_down" to "is_pressed" to maintain consistency. Modified the docs in places where 'down/up' were used to maintain consistency.

Testing

I haven't tested this in any way beside the checks from rust analyzer and the examples in the examples/ directory.

---

Migration Guide

bevy_picking/src/pointer.rs:

enum PressDirection:

• PressDirection::Down changes to PressDirection::Pressed.

• PressDirection::Up changes to PressDirection::Released.

  These changes are also relevant when working with enum PointerAction

bevy_picking/src/events.rs:

Clicking and pressing Events in events.rs categories change from [Down], [Up], [Click] to [Pressed], [Released], [Click].

• struct Down changes to struct Pressed - fires when a pointer button is pressed over the 'target' entity.
• struct Up changes to struct Released - fires when a pointer button is released over the 'target' entity.
• struct Click now fires when a pointer sends a Pressed event followed by a Released event on the same 'target'.
• struct DragStart now fires when the 'target' entity receives a pointer Pressed event followed by a pointer Move event.
• struct DragEnd now fires when the 'target' entity is being dragged and receives a pointer Released event.
• PickingEventWriters<'w>::down_events: EventWriter<'w, Pointer<Down>> changes to PickingEventWriters<'w>::pressed_events: EventWriter<'w, Pointer<Pressed>>.
• PickingEventWriters<'w>::up_events changes to PickingEventWriters<'w>::released_events.

[github-actions[bot]]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[mnmaita]

Looks good codewise. Could you please elaborate the details in the Migration Guide? The information there ends up in the website's migration guide, as far as I understand, so a list of the old and new names of the changed elements will be appreciated. Thanks!

[alice-i-cecile]

I like this rename, but the migration guide definitely needs work :)

[harun-ibram]

I updated the Migration Guide

[cart]

I support this in principle (though I've not read the code) as long as we keep it in the 0.16 milestone.

Why? This is a simple rename. We could avoid breaking people unnecessarily (and avoid a full cycle with the confusing mismatch) if we merge for 0.15

[cart]

(Moved to 0.15, just so we don't forget to finish this conversation before release, not because I'm putting my foot down)

[brandon-reinhart]

(Moved to 0.15, just so we don't forget to finish this conversation before release, not because I'm putting my foot down)

You mean pressing your foot?

[alice-i-cecile]

The argument against doing this now is to ease migration for bevy_mod_picking users. I don't feel strongly either way: it's just a rename refactor.

[NthTensor]

My vote is still to do this in 0.16. I was hoping to have as minimal divergence from the original as possible, and this is one case where I would actually prefer to break people's code twice rather than increase the hamming distance from the bevy_mod_picking. Especially since it seems likely we will be doing another pass at the picking events in 0.16 anyway.

[cart]

I was hoping to have as minimal divergence from the original as possible, and this is one case where I would actually prefer to break people's code twice rather than increase the hamming distance from the bevy_mod_picking

My take is that breaking everyone (including new users) is less preferable than making an already-breaking picking migration ever so slightly harder. I'd prefer to do this now unless people think the rename itself is too controversial (which doesn't seem to be the case).

Especially since it seems likely we will be doing another pass at the picking events in 0.16 anyway.

This might sway me. Whats the context?

[NthTensor]

To be totally transparent: I have an interest in keeping the migration painless for existing users, because I am expecting to have to migrate some fairly large projects to this once it's released, and I want to minimize the work I have to do. I'm content to be overruled, if that's your decision.

This might sway me. Whats the context?

There's some issues with the current picking events, and I think we'll identify more as we continue to use them. They are in a weird quasi-compliant relationship with the w3c spec, are missing essential variants such as Enter and Leave, and are straddling two awkward state machines, one of which only updates once per frame and cares about the start and end data, and the other for every OS input event (often multiple times a frame) and cares about intermediate values.

There's been a fair amount of discussion about what we want to do about these issues, and it has given me the impression that the picking events will be subject to a fair amount of churn in 0.16. That's why I think doing this now vs later will represent a pretty negligible dent in the migration work for the next release. But it's a small change, and you could say something similar the other way around. So eh it's fine either way.

[atlv24]

seconding punting to 0.16. consistency isnt as important as migration ease imo. there's plenty of mod picking users, making it easier for them to jump ship is worth it. renames are easy to migrate when in isolation, but conflate them with more changes and they become tougher

[cart]

Alrighty. Imo we're over-prioritizing migration ease (in this case), but I'll defer to the crowd on this one.