From 5c452c6c0049bac1cab054f9644e3c64431d6be2 Mon Sep 17 00:00:00 2001
From: Daniel Miller <earthmark.miller@gmail.com>
Date: Mon, 22 Apr 2024 10:48:46 -0700
Subject: [PATCH] Added `ButtonInput` docs usage example (#13046)

# Objective

Fixes #12470

This adds a examples for `ButtonInput` with `KeyCode`, `MouseButton`,
and `GamepadButton`.

It also includes an example of checking a multi-key combination, and
checking multiple keys to mean roughly the same thing.
---
 crates/bevy_input/src/button_input.rs | 75 +++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/crates/bevy_input/src/button_input.rs b/crates/bevy_input/src/button_input.rs
index 66e1435298..967bf850de 100644
--- a/crates/bevy_input/src/button_input.rs
+++ b/crates/bevy_input/src/button_input.rs
@@ -67,6 +67,81 @@ use bevy_ecs::schedule::State;
 ///
 /// `ButtonInput<GamepadButton>` is independent of window focus.
 ///
+/// ## Examples
+///
+/// Reading and checking against the current set of pressed buttons:
+/// ```no_run
+/// # use bevy_app::{App, NoopPluginGroup as DefaultPlugins, Update};
+/// # use bevy_ecs::{prelude::{IntoSystemConfigs, Res, Resource, resource_changed}, schedule::Condition};
+/// # use bevy_input::{ButtonInput, prelude::{GamepadButton, KeyCode, MouseButton}};
+///
+/// fn main() {
+///     App::new()
+///         .add_plugins(DefaultPlugins)
+///         .add_systems(
+///             Update,
+///             print_gamepad.run_if(resource_changed::<ButtonInput<GamepadButton>>),
+///         )
+///         .add_systems(
+///             Update,
+///             print_mouse.run_if(resource_changed::<ButtonInput<MouseButton>>),
+///         )
+///         .add_systems(
+///             Update,
+///             print_keyboard.run_if(resource_changed::<ButtonInput<KeyCode>>),
+///         )
+///         .run();
+/// }
+///
+/// fn print_gamepad(gamepad: Res<ButtonInput<GamepadButton>>) {
+///     println!("Gamepad: {:?}", gamepad.get_pressed().collect::<Vec<_>>());
+/// }
+///
+/// fn print_mouse(mouse: Res<ButtonInput<MouseButton>>) {
+///     println!("Mouse: {:?}", mouse.get_pressed().collect::<Vec<_>>());
+/// }
+///
+/// fn print_keyboard(keyboard: Res<ButtonInput<KeyCode>>) {
+///     if keyboard.any_pressed([KeyCode::ControlLeft, KeyCode::ControlRight])
+///         && keyboard.any_pressed([KeyCode::AltLeft, KeyCode::AltRight])
+///         && keyboard.any_pressed([KeyCode::ShiftLeft, KeyCode::ShiftRight])
+///         && keyboard.any_pressed([KeyCode::SuperLeft, KeyCode::SuperRight])
+///         && keyboard.pressed(KeyCode::KeyL)
+///     {
+///         println!("On Windows this opens LinkedIn.");
+///     } else {
+///         println!("keyboard: {:?}", keyboard.get_pressed().collect::<Vec<_>>());
+///     }
+/// }
+/// ```
+///
+/// Accepting input from multiple devices:
+/// ```no_run
+/// # use bevy_app::{App, NoopPluginGroup as DefaultPlugins, Update};
+/// # use bevy_ecs::{prelude::IntoSystemConfigs, schedule::Condition};
+/// # use bevy_input::{ButtonInput, common_conditions::{input_just_pressed}, prelude::{GamepadButton, Gamepad, GamepadButtonType, KeyCode}};
+///
+/// fn main() {
+///     App::new()
+///         .add_plugins(DefaultPlugins)
+///         .add_systems(
+///             Update,
+///             something_used.run_if(
+///                 input_just_pressed(KeyCode::KeyE)
+///                     .or_else(input_just_pressed(GamepadButton::new(
+///                         Gamepad::new(0),
+///                         GamepadButtonType::West,
+///                     ))),
+///             ),
+///         )
+///         .run();
+/// }
+///
+/// fn something_used() {
+///     println!("Generic use-ish button pressed.");
+/// }
+/// ```
+///
 /// ## Note
 ///
 /// When adding this resource for a new input type, you should: