Key Concepts
Handlers

Event Handlers

A finger on a touch-screen, emitting lightning where it touches

A finger on a touch-screen, emitting lightning where it touches

#[pax(
    <Rectangle @click=self.handle_click>
)]
pub struct HelloEvents {}
impl HelloEvents {
    pub fn handle_click(&mut self, _ctx: &NodeContext, args: Event<Click>) {
 
    }
}

In the above example, on_click=self.handle_click binds a the handle_click method defined in the host codebase to the built-in click event which Pax fires when a user clicks the mouse on this element.

Events fire as "interrupts" and are allowed to execute arbitrary, side-effectful, imperative logic — anything you can write or use in Rust.

It is inside event handlers that you will normally change property values, using .set or .ease_to.

Pax includes a number of built-in user interaction events like @click and @tap. These can all be bound and handled in the same manner.

There are two types of events in Pax:

Lifecycle Events

Lifecycle events run at the various points of the lifecycle a component.

Lifecycle events are registered in a settings block on a Pax Template:

#[pax(
    <Rectangle>
    
    @settings {
        @tick: handle_tick
    }
)]
pub struct HelloEvents {}
impl HelloEvents {
    pub fn handle_tick(&mut self, _ctx: &NodeContext) {
 
    }
}

Pax exposes three lifecycle events:

Tick

Tick is a fundamental unit of pax-engine, similar to a clock cycle. If you want a computation to happen every frame, you likely want to put it in the tick method.

Mount

Mount runs whenever a component is placed in the scene. It should run once per component.

Pre-render

Pre-render runs every frame like tick but right before the component is rendered.

Input Events

Input events run when user's interact with the Pax UI.

Here's an example of adding click handler to the HelloEvents component:

#[pax(
    <Rectangle @click=self.handle_click>
)]
pub struct HelloEvents {}
impl HelloEvents {
    pub fn handle_click(&mut self, _ctx: &NodeContext, args: Event<Click>) {
 
    }
}

You can attach an input event handler to any node in a template with an inline binding (@name_of_event=name_of_function) on the tag. The associated function is implemented in the Component's impl block as seen above. The arguments for all events can be found here (opens in a new tab).

Pax supports the following input events:

  • Scroll (@scroll)
  • Clap (@clap)
  • TouchStart (@touch_start)
  • TouchMove (@touch_move)
  • TouchEnd (@touch_end)
  • KeyDown (@key_down)
  • KeyUp (@key_up)
  • KeyPress (@key_press)
  • CheckboxChange (@checkbox_change)
  • ButtonClick (@button_click)
  • TextboxChange (@textbox_change)
  • TextInput (@text_input)
  • TextboxInput (@textbox_input)
  • Click (@click)
  • MouseDown (@mouse_down)
  • MouseUp (@mouse_up)
  • MouseMove (@mouse_move)
  • MouseOver (@mouse_over)
  • MouseOut (@mouse_out)
  • DoubleClick (@double_click)
  • ContextMenu (@context_menu)
  • Wheel (@wheel)
ExpressionsPrimitives