Deprecate ReceivedCharacter

[chompaa]

Objective

• Partially resolves Deprecate then remove ReceivedCharacter #12639.

Solution

• Deprecate ReceivedCharacter.
• Replace ReceivedCharacter with KeyboardInput in the relevant examples.

Migration Guide

• ReceivedCharacter is now deprecated, use KeyboardInput instead.

• Before:

  fn listen_characters(events: EventReader<ReceivedCharacter>) {
    for event in events.read() {
      info!("{}", event.char);
    }
  }

  After:

  fn listen_characters(events: EventReader<KeyboardInput>) {
    for event in events.read() {
      // Only check for characters when the key is pressed.
      if event.state == ButtonState::Released {
        continue;
      }
      // Note that some keys such as `Space` and `Tab` won't be detected as before.
      // Instead, check for them with `Key::Space` and `Key::Tab`.
      if let Key::Character(character) = &event.logical_key {
        info!("{}", character);
      }
    }
  }

[alice-i-cecile]

What needs to be done before you can take this out of draft?

[hymm]

If we deprecate received character, what's the recommended way to say get a capital character for a text box

[chompaa]

What needs to be done before you can take this out of draft?

Just need to fix the CI errors, should have time shortly :)

[chompaa]

If we deprecate received character, what's the recommended way to say get a capital character for a text box

See the updated char_input_events example in this PR. It should record capital characters.

[james7132]

These should be localized to where they're supposed to be used.

[chompaa]

How is this achieved for the WinitEvent enum in winit_event.rs? I've tried the following placements:

#[allow(deprecated)]
pub enum WinitEvent {
  // ..
  #[allow(deprecated)]
  ReceivedCharacter(#[allow(deprecated)] ReceivedCharacter),
  // ..
}

but clippy still seems to complain.

[hymm]

I think it needs to go on the functions that use the WinitEvent

[hymm]

See the updated char_input_events example in this PR. It should record capital characters.

I tried it out and it does seem to provide what is needed, but it's not an exact 1-1 replacement, since it includes both pressed and released events. The equivalent to ReceivedCharacter would be if you filtered out the Released events. Could you something like the following code snippet in the migration guide.

// Before
fn my_system(events: EventReader<ReceivedCharater>) {
  for event in events.read() {
    info!("{}", event.char);
  }
}
// After
fn my_system(events: EventReader<ReceivedCharater>) {
  for event in events.read().filter(|event| event.state == ButtonState::Released) {
    if let Key::Character(character) = &event.logical_key {
      info!("{}", character);
    }
  }
}

[chompaa]

I tried it out and it does seem to provide what is needed, but it's not an exact 1-1 replacement, since it includes both pressed and released events. The equivalent to ReceivedCharacter would be if you filtered out the Released events. Could you something like the following code snippet in the migration guide.

Yeah I accounted for this in the text_input example but not in char_input_events one it seems. I'll add it to the migration guide too.

[alice-i-cecile]

Generally looks good: the migration guide is solid. I won't block on figuring out how to localize those deprecated warnings: they'll be cleaned up shortly after the release anyways.

[hymm]

I won't block on figuring out how to localize those deprecated warnings: they'll be cleaned up shortly after the release anyways.

Does clippy warn on unused allows? If it doesn't we might want to leave some TODO's to remove the allow(deprecated)'s once ReceivedCharacter is removed.