event

An event declaration sets up an event handler – a procedure that gets called when an event is triggered. Events include initialization, start of a new frame, and user inputs, such as a keyboard press or mouse click. This allows creation of interactive scripts, as well as simple games.

The syntax is as follows: 

event <event type>(<argument1, argument2, ...>) = <procedure>;

procedure is either the name of a function, or, in case texture data need to be processed, a function name wrapped as a glsl( ) initializer. In the latter case, the code will run on the GPU, making it more expensive, as synchronization between CPU and GPU takes place. Because of this, it is recommended to only use this when necessary.

Event handlers triggered by keyboard and mouse may override some keyboard shortcuts and other functionality, such as drag and drop. Holding the reserved Ctrl key should reenable most of the affected GUI features.

The event's arguments, as well as the procedure's argument types, depend on the event type. The procedure's return type should be void.

Event types

List of available event types along with their arguments.

  • initialize() – triggered once at the very beginning, has no input arguments. Since images and animations are not yet evaluated at this point, attempting to sample them will yield blank pixels.
  • update() – triggered at the beginning of each frame except the first one, when initialize is triggered instead. Therefore, all images are already evaluated at this point. The procedure may have zero arguments, or one float argument, which is the elapsed time since the previous frame, in seconds.
  • press(<keys, mouse buttons>) – one or more keyboard keys and mouse buttons must be specified (separated by commas). It is then triggered whenever one of those is pressed. procedure has no arguments. The complete list of keys and mouse buttons can be found below.
  • release(<keys, mouse buttons>) – triggered when one of the specified keys or mouse buttons is released. procedure has no arguments.
  • mouse_press(<mouse buttons>) – unlike press, only left_button, middle_button, or right_button may be specified, but also reports mouse position to procedure. If procedure's argument type is vec2, mouse position will be reported as texture coordinate (between [0, 0] and [1, 1]). If it is ivec2, it will be reported as pixels from the bottom left corner. If this information is not needed, use press instead.
  • mouse_release(<mouse buttons>) – same as mouse_press, but triggered when a button is released.
  • mouse_position(<mouse button (optional)>) – triggered when the mouse position changes. If a mouse button is specified, it is only triggered while the button is held. If procedure's argument type is vec2, mouse position will be reported as texture coordinate. If it is ivec2, it will be reported as pixels from the bottom left corner. Keep in mind that if mouse is dragged outside the window, the reported coordinate may be outside the expected range.
  • mouse_delta(<mouse button (optional)>) – same as mouse_position, but reports the difference from the previous mouse position instead of an absolute coordinate.
  • button(<label>) – creates a button element in the GUI with a string label, triggered when the button is pressed. procedure has no arguments.

For keyboard and mouse events, the name of an object can optionally be passed as the first argument, causing the event to only be triggered by that object.

Example: 

var int clickCounter = 0;

void click(vec2 mousePos) {
    if (distance(itemPos, mousePos) < r)
        ++clickCounter;
}

event mouse_press(left_button) = click;

Inline event handler

As a shortcut, it is also possible to define the event handler function body directly in the event declaration. The previous example can thus be rewritten as: 

var int clickCounter = 0;

event mouse_press(left_button, vec2 mousePos) {
    if (distance(itemPos, mousePos) < r)
        ++clickCounter;
}

List of keys and buttons

  • left_button, middle_button, right_button – mouse buttons
  • scroll_up, scroll_down – mouse wheel
  • A, B, C, ... – letter keys
  • 0, 1, 2, ... – number keys (top row)
  • left_arrow, right_arrow, up_arrow, down_arrow
  • shift
  • space
  • enter
  • tab
  • num_0, num_1, num_2, ... – numeric keypad
  • num_add, num_subtract, num_multiply, num_divide, num_decimal
  • minus
  • plus
  • backspace
  • insert
  • delete
  • home, end
  • page_up, page_down
  • tilde
  • comma
  • period
  • slash
  • semicolon
  • quote
  • left_bracket, right_bracket
  • backslash

Other keys not listed here (specifically Ctrl, Alt, and function keys such as F1, ...) cannot be captured by an event handler.