
# Objective As discussed in #14275, Bevy is currently too prone to panic, and makes the easy / beginner-friendly way to do a large number of operations just to panic on failure. This is seriously frustrating in library code, but also slows down development, as many of the `Query::single` panics can actually safely be an early return (these panics are often due to a small ordering issue or a change in game state. More critically, in most "finished" products, panics are unacceptable: any unexpected failures should be handled elsewhere. That's where the new With the advent of good system error handling, we can now remove this. Note: I was instrumental in a) introducing this idea in the first place and b) pushing to make the panicking variant the default. The introduction of both `let else` statements in Rust and the fancy system error handling work in 0.16 have changed my mind on the right balance here. ## Solution 1. Make `Query::single` and `Query::single_mut` (and other random related methods) return a `Result`. 2. Handle all of Bevy's internal usage of these APIs. 3. Deprecate `Query::get_single` and friends, since we've moved their functionality to the nice names. 4. Add detailed advice on how to best handle these errors. Generally I like the diff here, although `get_single().unwrap()` in tests is a bit of a downgrade. ## Testing I've done a global search for `.single` to track down any missed deprecated usages. As to whether or not all the migrations were successful, that's what CI is for :) ## Future work ~~Rename `Query::get_single` and friends to `Query::single`!~~ ~~I've opted not to do this in this PR, and smear it across two releases in order to ease the migration. Successive deprecations are much easier to manage than the semantics and types shifting under your feet.~~ Cart has convinced me to change my mind on this; see https://github.com/bevyengine/bevy/pull/18082#discussion_r1974536085. ## Migration guide `Query::single`, `Query::single_mut` and their `QueryState` equivalents now return a `Result`. Generally, you'll want to: 1. Use Bevy 0.16's system error handling to return a `Result` using the `?` operator. 2. Use a `let else Ok(data)` block to early return if it's an expected failure. 3. Use `unwrap()` or `Ok` destructuring inside of tests. The old `Query::get_single` (etc) methods which did this have been deprecated.
145 lines
4.5 KiB
Rust
145 lines
4.5 KiB
Rust
//! This example illustrates drag move and drag resize without window
|
|
//! decorations.
|
|
//!
|
|
//! When window decorations are not present, the user cannot drag a window by
|
|
//! its titlebar to change its position. The `start_drag_move()` function
|
|
//! permits a user to drag a window by left clicking anywhere in the window;
|
|
//! left click must be pressed and other constraints can be imposed. For
|
|
//! instance an application could require a user to hold down alt and left click
|
|
//! to drag a window.
|
|
//!
|
|
//! The `start_drag_resize()` function behaves similarly but permits a window to
|
|
//! be resized.
|
|
use bevy::{math::CompassOctant, prelude::*};
|
|
|
|
/// Determine what do on left click.
|
|
#[derive(Resource, Debug)]
|
|
enum LeftClickAction {
|
|
/// Do nothing.
|
|
Nothing,
|
|
/// Move the window on left click.
|
|
Move,
|
|
/// Resize the window on left click.
|
|
Resize,
|
|
}
|
|
|
|
/// What direction index should the window resize toward.
|
|
#[derive(Resource)]
|
|
struct ResizeDir(usize);
|
|
|
|
/// Directions that the drag resizes the window toward.
|
|
const DIRECTIONS: [CompassOctant; 8] = [
|
|
CompassOctant::North,
|
|
CompassOctant::NorthEast,
|
|
CompassOctant::East,
|
|
CompassOctant::SouthEast,
|
|
CompassOctant::South,
|
|
CompassOctant::SouthWest,
|
|
CompassOctant::West,
|
|
CompassOctant::NorthWest,
|
|
];
|
|
|
|
fn main() {
|
|
App::new()
|
|
.add_plugins(DefaultPlugins.set(WindowPlugin {
|
|
primary_window: Some(Window {
|
|
decorations: false,
|
|
..default()
|
|
}),
|
|
..default()
|
|
}))
|
|
.insert_resource(ResizeDir(7))
|
|
.insert_resource(LeftClickAction::Move)
|
|
.add_systems(Startup, setup)
|
|
.add_systems(Update, (handle_input, move_or_resize_windows))
|
|
.run();
|
|
}
|
|
|
|
fn setup(mut commands: Commands) {
|
|
// Camera
|
|
commands.spawn(Camera3d::default());
|
|
|
|
// UI
|
|
commands
|
|
.spawn((
|
|
Node {
|
|
position_type: PositionType::Absolute,
|
|
padding: UiRect::all(Val::Px(5.0)),
|
|
..default()
|
|
},
|
|
BackgroundColor(Color::BLACK.with_alpha(0.75)),
|
|
GlobalZIndex(i32::MAX),
|
|
))
|
|
.with_children(|p| {
|
|
p.spawn(Text::default()).with_children(|p| {
|
|
p.spawn(TextSpan::new(
|
|
"Demonstrate drag move and drag resize without window decorations.\n\n",
|
|
));
|
|
p.spawn(TextSpan::new("Controls:\n"));
|
|
p.spawn(TextSpan::new("A - change left click action ["));
|
|
p.spawn(TextSpan::new("Move"));
|
|
p.spawn(TextSpan::new("]\n"));
|
|
p.spawn(TextSpan::new("S / D - change resize direction ["));
|
|
p.spawn(TextSpan::new("NorthWest"));
|
|
p.spawn(TextSpan::new("]\n"));
|
|
});
|
|
});
|
|
}
|
|
|
|
fn handle_input(
|
|
input: Res<ButtonInput<KeyCode>>,
|
|
mut action: ResMut<LeftClickAction>,
|
|
mut dir: ResMut<ResizeDir>,
|
|
example_text: Query<Entity, With<Text>>,
|
|
mut writer: TextUiWriter,
|
|
) -> Result {
|
|
use LeftClickAction::*;
|
|
if input.just_pressed(KeyCode::KeyA) {
|
|
*action = match *action {
|
|
Move => Resize,
|
|
Resize => Nothing,
|
|
Nothing => Move,
|
|
};
|
|
*writer.text(example_text.single()?, 4) = format!("{:?}", *action);
|
|
}
|
|
|
|
if input.just_pressed(KeyCode::KeyS) {
|
|
dir.0 = dir
|
|
.0
|
|
.checked_sub(1)
|
|
.unwrap_or(DIRECTIONS.len().saturating_sub(1));
|
|
*writer.text(example_text.single()?, 7) = format!("{:?}", DIRECTIONS[dir.0]);
|
|
}
|
|
|
|
if input.just_pressed(KeyCode::KeyD) {
|
|
dir.0 = (dir.0 + 1) % DIRECTIONS.len();
|
|
*writer.text(example_text.single()?, 7) = format!("{:?}", DIRECTIONS[dir.0]);
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
|
|
fn move_or_resize_windows(
|
|
mut windows: Query<&mut Window>,
|
|
action: Res<LeftClickAction>,
|
|
input: Res<ButtonInput<MouseButton>>,
|
|
dir: Res<ResizeDir>,
|
|
) {
|
|
// Both `start_drag_move()` and `start_drag_resize()` must be called after a
|
|
// left mouse button press as done here.
|
|
//
|
|
// winit 0.30.5 may panic when initiated without a left mouse button press.
|
|
if input.just_pressed(MouseButton::Left) {
|
|
for mut window in windows.iter_mut() {
|
|
match *action {
|
|
LeftClickAction::Nothing => (),
|
|
LeftClickAction::Move => window.start_drag_move(),
|
|
LeftClickAction::Resize => {
|
|
let d = DIRECTIONS[dir.0];
|
|
window.start_drag_resize(d);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|