mirror of
https://github.com/bevyengine/bevy
synced 2024-11-25 22:20:20 +00:00
Update input.rs
docs in bevy_input
(#4521)
# Objective - Part of the splitting process of #3692. ## Solution - Document `input.rs` inside of `bevy_input`.
This commit is contained in:
parent
2a5202637f
commit
46ff9fef98
1 changed files with 28 additions and 21 deletions
|
@ -7,6 +7,8 @@ use bevy_ecs::schedule::State;
|
|||
|
||||
/// A "press-able" input of type `T`.
|
||||
///
|
||||
/// ## Usage
|
||||
///
|
||||
/// This type can be used as a resource to keep the current state of an input, by reacting to
|
||||
/// events from the input. For a given input value:
|
||||
///
|
||||
|
@ -14,14 +16,16 @@ use bevy_ecs::schedule::State;
|
|||
/// * [`Input::just_pressed`] will return `true` for one frame after a press event.
|
||||
/// * [`Input::just_released`] will return `true` for one frame after a release event.
|
||||
///
|
||||
/// ## Multiple systems
|
||||
///
|
||||
/// In case multiple systems are checking for [`Input::just_pressed`] or [`Input::just_released`]
|
||||
/// but only one should react, for example in the case of triggering
|
||||
/// [`State`] change, you should consider clearing the input state, either by:
|
||||
/// [`State`](bevy_ecs::schedule::State) change, you should consider clearing the input state, either by:
|
||||
///
|
||||
/// * Using [`Input::clear_just_pressed`] or [`Input::clear_just_released`] instead.
|
||||
/// * Calling [`Input::clear`] or [`Input::reset`] immediately after the state change.
|
||||
///
|
||||
/// ## Notes when adding this resource for a new input type
|
||||
/// ## Note
|
||||
///
|
||||
/// When adding this resource for a new input type, you should:
|
||||
///
|
||||
|
@ -30,8 +34,11 @@ use bevy_ecs::schedule::State;
|
|||
/// * Call the [`Input::clear`] method at each frame start, before processing events.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Input<T: Eq + Hash> {
|
||||
/// A collection of every button that is currently being pressed.
|
||||
pressed: HashSet<T>,
|
||||
/// A collection of every button that has just been pressed.
|
||||
just_pressed: HashSet<T>,
|
||||
/// A collection of every button that has just been released.
|
||||
just_released: HashSet<T>,
|
||||
}
|
||||
|
||||
|
@ -49,7 +56,7 @@ impl<T> Input<T>
|
|||
where
|
||||
T: Copy + Eq + Hash,
|
||||
{
|
||||
/// Register a press for input `input`.
|
||||
/// Registers a press for the given `input`.
|
||||
pub fn press(&mut self, input: T) {
|
||||
// Returns `true` if the `input` wasn't pressed.
|
||||
if self.pressed.insert(input) {
|
||||
|
@ -57,17 +64,17 @@ where
|
|||
}
|
||||
}
|
||||
|
||||
/// Check if `input` has been pressed.
|
||||
/// Returns `true` if the `input` has been pressed.
|
||||
pub fn pressed(&self, input: T) -> bool {
|
||||
self.pressed.contains(&input)
|
||||
}
|
||||
|
||||
/// Check if any item in `inputs` has been pressed.
|
||||
/// Returns `true` if any item in `inputs` has been pressed.
|
||||
pub fn any_pressed(&self, inputs: impl IntoIterator<Item = T>) -> bool {
|
||||
inputs.into_iter().any(|it| self.pressed(it))
|
||||
}
|
||||
|
||||
/// Register a release for input `input`.
|
||||
/// Registers a release for the given `input`.
|
||||
pub fn release(&mut self, input: T) {
|
||||
// Returns `true` if the `input` was pressed.
|
||||
if self.pressed.remove(&input) {
|
||||
|
@ -75,64 +82,64 @@ where
|
|||
}
|
||||
}
|
||||
|
||||
/// Check if `input` has been just pressed.
|
||||
/// Returns `true` if the `input` has just been pressed.
|
||||
pub fn just_pressed(&self, input: T) -> bool {
|
||||
self.just_pressed.contains(&input)
|
||||
}
|
||||
|
||||
/// Check if any item in `inputs` has just been pressed.
|
||||
/// Returns `true` if any item in `inputs` has just been pressed.
|
||||
pub fn any_just_pressed(&self, inputs: impl IntoIterator<Item = T>) -> bool {
|
||||
inputs.into_iter().any(|it| self.just_pressed(it))
|
||||
}
|
||||
|
||||
/// Clear the "just pressed" state of `input`. Future calls to [`Input::just_pressed`] for the
|
||||
/// given input will return false until a new press event occurs.
|
||||
/// Returns true if `input` is currently "just pressed"
|
||||
/// Clears the `just_pressed` state of the `input` and returns `true` if the `input` has just been pressed.
|
||||
///
|
||||
/// Future calls to [`Input::just_pressed`] for the given input will return false until a new press event occurs.
|
||||
pub fn clear_just_pressed(&mut self, input: T) -> bool {
|
||||
self.just_pressed.remove(&input)
|
||||
}
|
||||
|
||||
/// Check if `input` has been just released.
|
||||
/// Returns `true` if the `input` has just been released.
|
||||
pub fn just_released(&self, input: T) -> bool {
|
||||
self.just_released.contains(&input)
|
||||
}
|
||||
|
||||
/// Check if any item in `inputs` has just been released.
|
||||
/// Returns `true` if any item in `inputs` has just been released.
|
||||
pub fn any_just_released(&self, inputs: impl IntoIterator<Item = T>) -> bool {
|
||||
inputs.into_iter().any(|it| self.just_released(it))
|
||||
}
|
||||
|
||||
/// Clear the "just released" state of `input`. Future calls to [`Input::just_released`] for the
|
||||
/// given input will return false until a new release event occurs.
|
||||
/// Returns true if `input` is currently "just released"
|
||||
/// Clears the `just_released` state of the `input` and returns `true` if the `input` has just been released.
|
||||
///
|
||||
/// Future calls to [`Input::just_released`] for the given input will return false until a new release event occurs.
|
||||
pub fn clear_just_released(&mut self, input: T) -> bool {
|
||||
self.just_released.remove(&input)
|
||||
}
|
||||
|
||||
/// Reset all status for input `input`.
|
||||
/// Clears the `pressed`, `just_pressed` and `just_released` data of the `input`.
|
||||
pub fn reset(&mut self, input: T) {
|
||||
self.pressed.remove(&input);
|
||||
self.just_pressed.remove(&input);
|
||||
self.just_released.remove(&input);
|
||||
}
|
||||
|
||||
/// Clear just pressed and just released information.
|
||||
/// Clears the `just pressed` and `just released` data for every input.
|
||||
pub fn clear(&mut self) {
|
||||
self.just_pressed.clear();
|
||||
self.just_released.clear();
|
||||
}
|
||||
|
||||
/// List all inputs that are pressed.
|
||||
/// An iterator visiting every pressed input in arbitrary order.
|
||||
pub fn get_pressed(&self) -> impl ExactSizeIterator<Item = &T> {
|
||||
self.pressed.iter()
|
||||
}
|
||||
|
||||
/// List all inputs that are just pressed.
|
||||
/// An iterator visiting every just pressed input in arbitrary order.
|
||||
pub fn get_just_pressed(&self) -> impl ExactSizeIterator<Item = &T> {
|
||||
self.just_pressed.iter()
|
||||
}
|
||||
|
||||
/// List all inputs that are just released.
|
||||
/// An iterator visiting every just released input in arbitrary order.
|
||||
pub fn get_just_released(&self) -> impl ExactSizeIterator<Item = &T> {
|
||||
self.just_released.iter()
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue