Mouse and keyboard events

Most user-input interaction in OPENRNDR manifests through events.

Mouse events

A simple demonstration of a listening for mouse button clicks looks as follows:

import org.openrndr.KEY_ARROW_LEFT
import org.openrndr.KEY_BACKSPACE
import org.openrndr.KeyModifier
import org.openrndr.application
import org.openrndr.math.Vector2

fun main() = application {
    program {
        mouse.buttonDown.listen {
            // -- it refers to a MouseEvent instance here
            println(it.position)
        }
    }
}

Every program has a mouse object that exposes events and mouse properties. In the example above we attach a listener to the clicked event. The {} block after listen is a short-hand notation for passing a function into listen.

There are some limitations to what the listener function can (or should) do. As a rule-of-thumb: don’t draw in events. The result of drawing in listener functions is that it does not work. You are encouraged to use listener functions to change the state of your program.

Let’s provide a commonly used pattern to deal with this limitation. The idea here is that we introduce variables in our program that are used to communicate between the listener function and the draw function.

import org.openrndr.KEY_ARROW_LEFT
import org.openrndr.KEY_BACKSPACE
import org.openrndr.KeyModifier
import org.openrndr.application
import org.openrndr.math.Vector2

fun main() = application {
    program {
        // -- a variable to keep of where we clicked
        // -- this is an "optional type" that can be set to null
        var drawPosition : Vector2? = null

        mouse.buttonDown.listen {
            drawPosition = it.position
        }

        extend {
            // -- check if the drawPosition is not null
            drawPosition?.let {
                drawer.circle(it.x, it.y, 100.0)
                // -- reset the drawPosition to null
                drawPosition = null
            }
        }
    }
}

Overview of mouse events

Keyboard events

OPENRNDR provides two classes of keyboard events. The first are key events, which should be used to respond to the user pressing or releasing buttons on the keyboard. The second class are character events, which should be used for handling text input as they also deal with composed characters.

To use the key events one listens to keyboard.keyDown events and compares the key value. For example:

import org.openrndr.KEY_ARROW_LEFT
import org.openrndr.KEY_BACKSPACE
import org.openrndr.KeyModifier
import org.openrndr.application
import org.openrndr.math.Vector2

fun main() = application {
    program {
        keyboard.keyDown.listen {
            // -- it refers to a KeyEvent instance here
            // -- compare the key value to a predefined key constant
            if (it.key == KEY_ARROW_LEFT) {
                // -- react to the keypress here
            }
        }
    }
}

import org.openrndr.KEY_ARROW_LEFT
import org.openrndr.KEY_BACKSPACE
import org.openrndr.KeyModifier
import org.openrndr.application
import org.openrndr.math.Vector2

fun main() = application {
    program {
        keyboard.keyDown.listen {
            // -- it refers to a KeyEvent instance here
            // -- compare the name value against "a"
            if (it.name == "a") {
                // -- react to the keypress here
            }
        }
    }
}

To use the character events one listens to keyboard.character events which provide character values. For example:

import org.openrndr.KEY_ARROW_LEFT
import org.openrndr.KEY_BACKSPACE
import org.openrndr.KeyModifier
import org.openrndr.application
import org.openrndr.math.Vector2

fun main() = application {
    var input = ""
    program {
        keyboard.character.listen {
            input += it.character
        }
        keyboard.keyDown.listen {
            // -- it refers to a KeyEvent instance here
            // -- compare the key value to a predefined key constant
            if (it.key == KEY_BACKSPACE) {
                if (input.isNotEmpty()) {
                    input = input.substring(0, input.length - 1)
                }
            }
        }
    }
}

Querying key modifiers

Checking for modifiers can be done by checking if the desired modifier key is active in modifiers. In the example below we check if both shift and the left arrow key are pressed.

import org.openrndr.KEY_ARROW_LEFT
import org.openrndr.KEY_BACKSPACE
import org.openrndr.KeyModifier
import org.openrndr.application
import org.openrndr.math.Vector2

fun main() = application {
    program {
        keyboard.keyDown.listen {
            if (it.key == KEY_ARROW_LEFT && KeyModifier.SHIFT in it.modifiers) {
                // -- react to the keypress here
            }
        }
    }
}

Note that also mouse events come with modifiers and can be queried in a similar way.

Overview of keyboard events

Overview of key constants

We provide constants for most of the functional/navigational keys.

Event processing order

Mouse and keyboard events are buffered and processed before draw() is called. It is possible but not advised to perform drawing on event.

edit on GitHub