API

A mouse button was released.

The pointer entered the window area.

A key was pressed. Note that some key combinations can be reserved by the OS, so they don't trigger the corresponding event. On Ubuntu 20.04, this is for example the case with some combinations of the form alt+fkey such as alt+f4.

A key was released.

Signals an absence of event.

A mouse button was pressed.

The pointer left the window area.

The pointer moves in the window.

The window was closed, e.g. manually by the user or by a programmatic action.

A window was exposed to the screen; either right after creation, or when it was previously hidden and then visible again.

The window gained focus.

The window is detected as invalid (for example, when closed externally).

The conditions for tagging a window as invalid depend on the windowing API used. It is typically used to signal that a window crashed or does not exist, but for which an event was reported. It may however not possible to know exactly why or when a window becomes invalid. For example, the X11 protocol does not offer a way to check for window validity, since the window may get invalidated by the time the X server answer comes back. Windows that are tagged invalid should be terminated.

The window lost focus.

The window was resized.

(::Type{<:AbstractWindow})(wm::AbstractWindowManager; kwargs...)

Create a window.

Abstract window type.

abstract type AbstractWindow

Entity that manages windows.

abstract type AbstractWindowManager

Generic event structure identified by its type (see EventType) and which may hold data depending on the type of event.

The type of data follows the association (with respect to the event type):

• KEY_PRESSED or KEY_RELEASED: KeyEvent, accessible with event.key_event
• BUTTON_PRESSED or BUTTON_RELEASED: MouseEvent, accessible with event.mouse_event
• POINTER_MOVED: PointerState, accessible with event.pointer_state
• WINDOW_RESIZED: Tuple{Float64,Float64} # new dimensions, accessible with event.new_dimensions
• WINDOW_EXPOSED: Tuple{Float64,Float64} # area to redraw, accessible with event.area
• Other event types: Nothing

struct Event{W<:AbstractWindow}

• type::EventType

• data::Any

• location::Tuple{Float64, Float64}

• time::Float64

• window::AbstractWindow

Event queue meant to hold events to be processed by an application.

The event queue is bound to a window manager, and will be filled upon notification of low-level events sent by that window manager. Only high-level events will be recorded in the event queue, which are typically suited for use in applications.

The event queue is infinitely iterable, returning Events as they are received. When no events are available, the queue will either enter a sleeping state of approximately 1 ms (if sleep = true) or spin while yielding at every iteration.

Any task iterating over the event queue is therefore a good candidate to be scheduled using an interactive thread from Julia 1.9 onwards.

Alternatively, the event queue may be manually filled with collect_events! and processed using Base.isempty and Base.popfirst!.

The parameter record_history may be set to true to save all events that have been processed (either by iteration or manual Base.popfirst!). Implementations of window managers may extend save_history and replay_history to allow for the saving and replay of events that have been stored. Note that record_history will have to be set to true for save_history to work.

struct EventQueue{WM<:AbstractWindowManager, W<:AbstractWindow}

• wm::AbstractWindowManager

• events::Array{Event{W}, 1} where W<:AbstractWindow

• history::Array{Event{W}, 1} where W<:AbstractWindow

• sleep::Bool

• record_history::Bool

Type of input or window event which may occur on a particular window.

This type is defined as a bitmask, to make it easier to work with sets of events.

struct EventType <: BitMasks.BitMask{UInt32}

• val::UInt32

Key binding associated to a character and a key modifier state.

struct KeyCombination

• key::KeySymbol

• exact_modifiers::ModifierState

• significant_modifiers::ModifierState

Details surrounding an event produced by a keystroke.

struct KeyEvent

• key_name::Symbol: The name of the physical key.

• key::KeySymbol: The symbol associated with the keystroke.

• input::Char: Printable input (can be the empty string).

• modifiers::ModifierState: Modifier state.

• consumed_modifiers::ModifierState: Modifiers that were used when translating the physical key into a key symbol.

Representation of a symbol that may be bound to a key, depending on a keyboard layout. It differs from the physical representation of a key, denoted by names such as AD01 which represent physical keys (in this case, q on a US keyboard). A key symbol is sent when a physical key is pressed, even if no input character is bound to the key. This structure provides a friendly symbol field, and a prettier description field (mostly used for printing). For example, the right arrow, with symbol :right_arrow (resp. :kp_right_arrow for keypad input), is represented by "→" (resp. "→ (keypad)").

There is no consistent representation, so the one provided here may differ from windowing API implementations.

struct KeySymbol

• name::Symbol

• description::Union{Char, String}

A mouse press/release associated to a certain state.

struct MouseEvent

• button::MouseButton

• state::MouseButton

Context in which a pointer motion was performed, including active mouse buttons and keyboard modifiers.

struct PointerState

• state::MouseButton

• modifiers::ModifierState

close(wm::AbstractWindowManager, window::AbstractWindow)

Close a window.

close(wm::AbstractWindowManager, _::AbstractWindow)

Gather all pending events.

collect_events!(queue::EventQueue)

Get window DPI.

dpi(window::AbstractWindow)

Window dimensions (width, height).

extent(window::AbstractWindow)

Retrieve a window given an identifier id, would typically be an integer identifier, a handle or a name.

get_window(wm::AbstractWindowManager, id)

Define an internal representation and a readable description for some key inputs.

The keys that are listed here are not exhaustive and only cover a very small subset of all possible keys.

key_symbol(name::Symbol) -> Any

Map a window to the screen.

map_window(window::AbstractWindow)

Non-blocking poll for events. Must return whether a client event was consumed, even if no Event is added to the queue.

poll_for_events!(queue::EventQueue)

replay_history(wm, events)

Replay events generated by save_history on the provided window manager.

Delays between events should be respected. The window manager is free to assume that no other event will be generated during the replay: user interactinos with the window while the replay is ongoing may affect the integrity of the replication.

Note that any global state such as RNG is not saved; the application is responsible for managing state appropriately for effects outside of the event system.

Resize the window with extent reflecting the new (width, height).

resize(window::AbstractWindow, extent)

save_history(wm::WM, queue::EventQueue{WM}) -> Vector{<:Event}

Save actions stored inside the event queue for later replay with replay_history.

The event queue must have been created with record_history = true.

Set window icon.

set_icon(window::AbstractWindow, icon)

Set window icon title.

set_icon_title(window::AbstractWindow, icon_title)

Set window title.

set_title(window::AbstractWindow, title)

Unmap a window from the screen.

unmap_window(window::AbstractWindow)

Retrieve all the AbstractWindows in use by wm.

windows(wm::AbstractWindowManager)

Construct a KeyCombination instance from a string as "[<state_1>+[...<state_n>+]]<key>". The string must be a list of elements separated by '+' characters, with only one key symbol at the end. For example, "k", "alt+k" and "ctrl+alt+shift+f11" are valid strings, but "k+a" is not. Casing is significant, as z and Z are different key symbols. For modifier strings, the casing should be lowercase, or will be forcefully converted into a lowercase string (reducing performance).