Trait pix_engine::engine::PixEngine
source · pub trait PixEngine {
Show 19 methods
// Required method
fn on_update(&mut self, s: &mut PixState) -> PixResult<()>;
// Provided methods
fn on_start(&mut self, s: &mut PixState) -> PixResult<()> { ... }
fn on_stop(&mut self, s: &mut PixState) -> PixResult<()> { ... }
fn on_key_pressed(
&mut self,
s: &mut PixState,
event: KeyEvent
) -> PixResult<bool> { ... }
fn on_key_released(
&mut self,
s: &mut PixState,
event: KeyEvent
) -> PixResult<bool> { ... }
fn on_key_typed(&mut self, s: &mut PixState, text: &str) -> PixResult<bool> { ... }
fn on_mouse_dragged(
&mut self,
s: &mut PixState,
pos: Point<i32>,
rel_pos: Point<i32>
) -> PixResult<bool> { ... }
fn on_controller_pressed(
&mut self,
s: &mut PixState,
event: ControllerEvent
) -> PixResult<bool> { ... }
fn on_controller_released(
&mut self,
s: &mut PixState,
event: ControllerEvent
) -> PixResult<bool> { ... }
fn on_controller_axis_motion(
&mut self,
s: &mut PixState,
controller_id: ControllerId,
axis: Axis,
value: i32
) -> PixResult<bool> { ... }
fn on_controller_update(
&mut self,
s: &mut PixState,
controller_id: ControllerId,
update: ControllerUpdate
) -> PixResult<bool> { ... }
fn on_mouse_pressed(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool> { ... }
fn on_mouse_released(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool> { ... }
fn on_mouse_clicked(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool> { ... }
fn on_mouse_dbl_clicked(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool> { ... }
fn on_mouse_motion(
&mut self,
s: &mut PixState,
pos: Point<i32>,
rel_pos: Point<i32>
) -> PixResult<bool> { ... }
fn on_mouse_wheel(
&mut self,
s: &mut PixState,
pos: Point<i32>
) -> PixResult<bool> { ... }
fn on_window_event(
&mut self,
s: &mut PixState,
window_id: WindowId,
event: WindowEvent
) -> PixResult<()> { ... }
fn on_event(&mut self, s: &mut PixState, event: &Event) -> PixResult<bool> { ... }
}
Expand description
Trait for allowing the Engine
to drive your application and send notification of events,
passing along a &mut PixState
to allow interacting with the Engine
.
Please see the module-level documentation for more examples.
Required Methods§
sourcefn on_update(&mut self, s: &mut PixState) -> PixResult<()>
fn on_update(&mut self, s: &mut PixState) -> PixResult<()>
Called after PixEngine::on_start
, every frame based on the target frame rate.
By default, this is called as often as possible but can be controlled by changing the
target frame rate. It will continue to be executed until the application is terminated,
or [PixState::run(false)
] is called.
After [PixState::run(false)
] is called, you can call PixState::redraw
or
PixState::run_times
to control the execution.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
.
Engine::run
will return the original error or any error returned from
PixEngine::on_stop
. Calling PixState::abort_quit
during PixEngine::on_stop
will
allow program execution to resume. Care should be taken as this could result in a loop if
the cause of the original error is not resolved.
Any errors encountered from methods on PixState
can either be handled by the
implementor, or propagated with the [?] operator.
Example
fn on_update(&mut self, s: &mut PixState) -> PixResult<()> {
if s.mouse_pressed() {
s.fill(color!(0));
} else {
s.fill(color!(255));
}
let m = s.mouse_pos();
s.circle([m.x(), m.y(), 80])?;
Ok(())
}
Provided Methods§
sourcefn on_start(&mut self, s: &mut PixState) -> PixResult<()>
fn on_start(&mut self, s: &mut PixState) -> PixResult<()>
Called once upon engine start when Engine::run
is called.
This can be used to set up initial state like creating objects, loading files or Images, or
any additional application state that’s either dynamic or relies on runtime values from
PixState
.
Errors
Returning an error will immediately exit the application and call PixEngine::on_stop
.
Engine::run
will return the original error or any error returned from
PixEngine::on_stop
.
Example
fn on_start(&mut self, s: &mut PixState) -> PixResult<()> {
s.background(220);
s.font_family(Font::NOTO)?;
s.font_size(16);
Ok(())
}
sourcefn on_stop(&mut self, s: &mut PixState) -> PixResult<()>
fn on_stop(&mut self, s: &mut PixState) -> PixResult<()>
Called when the engine detects a close/exit event such as calling PixState::quit
or if an
error is returned during program execution by any PixEngine
methods.
This can be used to clean up files or resources on appliation quit.
Errors
Returning an error will immediately exit the application by propagating the error and returning from
Engine::run
. Calling PixState::abort_quit
will allow program execution to
resume. Care should be taken as this could result in a loop if the cause of the original
error is not resolved.
Any errors encountered from methods on PixState
can either be handled by the
implementor, or propagated with the [?] operator.
Example
fn on_stop(&mut self, s: &mut PixState) -> PixResult<()> {
std::fs::remove_file(&self.resources)?;
Ok(())
}
sourcefn on_key_pressed(
&mut self,
s: &mut PixState,
event: KeyEvent
) -> PixResult<bool>
fn on_key_pressed( &mut self, s: &mut PixState, event: KeyEvent ) -> PixResult<bool>
Called each time a Key
is pressed with the KeyEvent
indicating which key and modifiers
are pressed as well as whether this is a repeat event where the key is being held down.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_key_pressed(&mut self, s: &mut PixState, event: KeyEvent) -> PixResult<bool> {
match event.key {
Key::Return if event.keymod == KeyMod::CTRL => {
s.fullscreen(true);
Ok(true)
},
_ => Ok(false),
}
}
sourcefn on_key_released(
&mut self,
s: &mut PixState,
event: KeyEvent
) -> PixResult<bool>
fn on_key_released( &mut self, s: &mut PixState, event: KeyEvent ) -> PixResult<bool>
Called each time a Key
is pressed with the KeyEvent
indicating which key and modifiers
are released.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_key_released(&mut self, s: &mut PixState, event: KeyEvent) -> PixResult<bool> {
match event.key {
Key::Space => {
self.fire_bullet(s);
Ok(true)
}
_ => Ok(false),
}
}
sourcefn on_key_typed(&mut self, s: &mut PixState, text: &str) -> PixResult<bool>
fn on_key_typed(&mut self, s: &mut PixState, text: &str) -> PixResult<bool>
Called each time text input is received.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_key_typed(&mut self, s: &mut PixState, text: &str) -> PixResult<bool> {
self.text.push_str(text);
Ok(true)
}
sourcefn on_mouse_dragged(
&mut self,
s: &mut PixState,
pos: Point<i32>,
rel_pos: Point<i32>
) -> PixResult<bool>
fn on_mouse_dragged( &mut self, s: &mut PixState, pos: Point<i32>, rel_pos: Point<i32> ) -> PixResult<bool>
Called each time the Mouse
is moved while any mouse button is being held.
You can inspect which button is being held by calling PixState::mouse_down
with the desired
Mouse button. See also: PixEngine::on_mouse_motion
.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_mouse_dragged(
&mut self,
s: &mut PixState,
pos: Point<i32>,
rel_pos: Point<i32>,
) -> PixResult<bool> {
self.pos = pos;
Ok(true)
}
sourcefn on_controller_pressed(
&mut self,
s: &mut PixState,
event: ControllerEvent
) -> PixResult<bool>
fn on_controller_pressed( &mut self, s: &mut PixState, event: ControllerEvent ) -> PixResult<bool>
Called each time a ControllerButton
is pressed with the ControllerEvent
indicating
which button is pressed.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_controller_pressed(&mut self, s: &mut PixState, event: ControllerEvent) -> PixResult<bool> {
match event.button {
ControllerButton::Start => {
self.pause();
Ok(true)
},
_ => Ok(false),
}
}
sourcefn on_controller_released(
&mut self,
s: &mut PixState,
event: ControllerEvent
) -> PixResult<bool>
fn on_controller_released( &mut self, s: &mut PixState, event: ControllerEvent ) -> PixResult<bool>
Called each time a ControllerButton
is pressed with the ControllerEvent
indicating
which key and modifiers are released.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_controller_released(&mut self, s: &mut PixState, event: ControllerEvent) -> PixResult<bool> {
match event.button {
ControllerButton::X => {
self.fire_bullet(s);
Ok(true)
}
_ => Ok(false),
}
}
sourcefn on_controller_axis_motion(
&mut self,
s: &mut PixState,
controller_id: ControllerId,
axis: Axis,
value: i32
) -> PixResult<bool>
fn on_controller_axis_motion( &mut self, s: &mut PixState, controller_id: ControllerId, axis: Axis, value: i32 ) -> PixResult<bool>
Called each time a Controller
Axis
is moved with the delta since last frame.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_controller_axis_motion(
&mut self,
s: &mut PixState,
controller_id: ControllerId,
axis: Axis,
value: i32,
) -> PixResult<bool> {
if controller_id == self.player1 {
match axis {
Axis::LeftX => {
if value > 0 {
self.move_right();
} else if value < 0 {
self.move_left();
}
Ok(true)
}
Axis::LeftY => {
if value > 0 {
self.move_up();
} else if value < 0 {
self.move_down();
}
Ok(true)
}
_ => Ok(false)
}
} else {
Ok(false)
}
}
sourcefn on_controller_update(
&mut self,
s: &mut PixState,
controller_id: ControllerId,
update: ControllerUpdate
) -> PixResult<bool>
fn on_controller_update( &mut self, s: &mut PixState, controller_id: ControllerId, update: ControllerUpdate ) -> PixResult<bool>
Called each time a Controller
is added, removed, or remapped.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_controller_update(
&mut self,
s: &mut PixState,
controller_id: ControllerId,
update: ControllerUpdate,
) -> PixResult<bool> {
match update {
ControllerUpdate::Added => {
self.add_gamepad(controller_id);
Ok(true)
}
ControllerUpdate::Removed => {
self.remove_gamepad(controller_id);
Ok(true)
}
_ => Ok(false),
}
}
sourcefn on_mouse_pressed(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool>
fn on_mouse_pressed( &mut self, s: &mut PixState, btn: Mouse, pos: Point<i32> ) -> PixResult<bool>
Called each time a Mouse
button is pressed.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_mouse_pressed(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>,
) -> PixResult<bool> {
if let Mouse::Left = btn {
if self.canvas.contains(pos) {
self.drawing = true;
}
}
Ok(true)
}
sourcefn on_mouse_released(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool>
fn on_mouse_released( &mut self, s: &mut PixState, btn: Mouse, pos: Point<i32> ) -> PixResult<bool>
Called each time a Mouse
button is released.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_mouse_released(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>,
) -> PixResult<bool> {
if let Mouse::Left = btn {
if self.canvas.contains(pos) {
self.drawing = false;
}
}
Ok(true)
}
sourcefn on_mouse_clicked(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool>
fn on_mouse_clicked( &mut self, s: &mut PixState, btn: Mouse, pos: Point<i32> ) -> PixResult<bool>
Called each time a Mouse
button is clicked (a press followed by a release).
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_mouse_clicked(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>,
) -> PixResult<bool> {
if let Mouse::Left = btn {
if self.item.contains(pos) {
self.selected = true;
}
}
Ok(true)
}
sourcefn on_mouse_dbl_clicked(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>
) -> PixResult<bool>
fn on_mouse_dbl_clicked( &mut self, s: &mut PixState, btn: Mouse, pos: Point<i32> ) -> PixResult<bool>
Called each time a Mouse
button is clicked twice within 500ms.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_mouse_dbl_clicked(
&mut self,
s: &mut PixState,
btn: Mouse,
pos: Point<i32>,
) -> PixResult<bool> {
if let Mouse::Left = btn {
if self.item.contains(pos) {
self.execute_item()
}
}
Ok(true)
}
sourcefn on_mouse_motion(
&mut self,
s: &mut PixState,
pos: Point<i32>,
rel_pos: Point<i32>
) -> PixResult<bool>
fn on_mouse_motion( &mut self, s: &mut PixState, pos: Point<i32>, rel_pos: Point<i32> ) -> PixResult<bool>
Called each time the Mouse
is moved with the (x, y)
screen coordinates and relative
(xrel, yrel)
positions since last frame.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_mouse_motion(
&mut self,
s: &mut PixState,
pos: Point<i32>,
rel_pos: Point<i32>,
) -> PixResult<bool> {
self.pos = pos;
Ok(true)
}
sourcefn on_mouse_wheel(
&mut self,
s: &mut PixState,
pos: Point<i32>
) -> PixResult<bool>
fn on_mouse_wheel( &mut self, s: &mut PixState, pos: Point<i32> ) -> PixResult<bool>
Called each time the Mouse
wheel is scrolled with the (x, y)
delta since last frame.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_mouse_wheel(&mut self, s: &mut PixState, pos: Point<i32>) -> PixResult<bool> {
self.scroll += pos;
Ok(true)
}
sourcefn on_window_event(
&mut self,
s: &mut PixState,
window_id: WindowId,
event: WindowEvent
) -> PixResult<()>
fn on_window_event( &mut self, s: &mut PixState, window_id: WindowId, event: WindowEvent ) -> PixResult<()>
Called each time a window event occurs.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_window_event(
&mut self,
s: &mut PixState,
window_id: WindowId,
event: WindowEvent,
) -> PixResult<()> {
if window_id == self.window_id {
match event {
WindowEvent::Minimized => self.pause(),
WindowEvent::Restored => self.unpause(),
_ => (),
}
}
Ok(())
}
sourcefn on_event(&mut self, s: &mut PixState, event: &Event) -> PixResult<bool>
fn on_event(&mut self, s: &mut PixState, event: &Event) -> PixResult<bool>
Called for any system or user event. This is a catch-all for handling any events not
covered by other PixEngine
methods.
Returning true
consumes this event, preventing any further event triggering.
Errors
Returning an error will start exiting the application and call PixEngine::on_stop
. See
the Errors
section in PixEngine::on_update
for more details.
Example
fn on_event(
&mut self,
s: &mut PixState,
event: &Event,
) -> PixResult<bool> {
match event {
Event::ControllerDown { controller_id, button } => {
// Handle controller down event
Ok(true)
}
Event::ControllerUp { controller_id, button } => {
// Handle controller up event
Ok(true)
}
_ => Ok(false),
}
}