Paper Input API: Keyboard, Mouse, Clipboard, and Events

Paper does not hook into any platform input API directly — you feed events to it each frame, and it maintains a full frame-aware input state that you can query anywhere in your UI code. All feed methods should be called before BeginFrame. Query methods can be called at any point between BeginFrame and EndFrame.

Input Feed Methods

Call these from your host application’s event handlers or polling loop, before paper.BeginFrame(...).

SetPointerPosition

public void SetPointerPosition(float x, float y)

Updates the pointer’s logical position without affecting any button state. Use when you receive a pure move event and have no button information to update.

float

required

Horizontal position in logical pixels.

float

required

Vertical position in logical pixels.

SetPointerState

public void SetPointerState(PaperMouseBtn btn, float x, float y, bool isPointerBtnDown, bool isPointerMove)

Updates both the pointer position and the state of a specific button. When isPointerMove is true, only the position is updated and the button state is left unchanged.

btn

PaperMouseBtn

required

The button whose state is being reported.

float

required

Current pointer X in logical pixels.

float

required

Current pointer Y in logical pixels.

isPointerBtnDown

bool

required

Whether btn is currently pressed.

isPointerMove

bool

required

When true, the call is treated as a move event and button state is not updated.

SetPointerWheel

public void SetPointerWheel(float wheel)

Sets the scroll wheel delta for this frame. Paper resets PointerWheel to 0 at the end of each EndFrame.

wheel

float

required

Wheel delta in logical scroll units. Positive = scroll down/forward.

AddInputCharacter

public void AddInputCharacter(string text)

Enqueues one or more characters into the text input queue. Carriage returns (\r) are normalised to newlines (\n). The queue is flushed to the focused element during EndFrame and cleared afterward.

text

string

required

The character(s) produced by this key event.

PushInputText

public void PushInputText(char character)

Enqueues a single character directly. Equivalent to AddInputCharacter for a one-character string.

character

char

required

Character to enqueue.

SetKeyState

public void SetKeyState(PaperKey key, bool isKeyDown)

Updates the state of a keyboard key. Also records LastKeyPressed when isKeyDown is true, and resets auto-repeat counters when isKeyDown is false.

key

PaperKey

required

The key whose state changed.

isKeyDown

bool

required

true for key-down; false for key-up.

ClearInput

public void ClearInput()

Resets all keyboard and pointer state to their initial values. Useful when the host window loses focus or a modal takes over and you want Paper to ignore stale held-key state.

Keyboard Query Methods

IsKeyDown

public bool IsKeyDown(PaperKey key)

return

bool

true while key is held this frame.

IsKeyUp

public bool IsKeyUp(PaperKey key)

return

bool

true while key is not held.

IsKeyPressed

public bool IsKeyPressed(PaperKey key)

return

bool

true only on the first frame the key transitions from up to down.

IsKeyReleased

public bool IsKeyReleased(PaperKey key)

return

bool

true only on the frame the key transitions from down to up.

IsKeyHeld

public bool IsKeyHeld(PaperKey key, float holdDuration = 0.5f)

holdDuration

float

default:"0.5"

Minimum seconds the key must have been continuously held.

return

bool

true if the key has been down for at least holdDuration seconds.

IsKeyRepeating

public bool IsKeyRepeating(PaperKey key)

return

bool

true when KeyAutoRepeatEnabled is true and the key has entered the auto-repeat phase (i.e., held past AutoRepeatDelay and firing at AutoRepeatRate).

IsKeyPressedOrRepeating

public bool IsKeyPressedOrRepeating(PaperKey key)

Combines IsKeyPressed and the auto-repeat check into a single call — the most convenient way to implement text-editor-style held-key behaviour.

return

bool

true if the key was just pressed this frame or is currently auto-repeating.

LastKeyPressed

public PaperKey LastKeyPressed { get; }

The most recently pressed key. Set when SetKeyState is called with isKeyDown = true. Not cleared between frames.

Mouse / Pointer Query Methods

IsPointerDown

public bool IsPointerDown(PaperMouseBtn btn)

return

bool

true while btn is held this frame.

IsPointerUp

public bool IsPointerUp(PaperMouseBtn btn)

return

bool

true while btn is not held.

IsPointerPressed

public bool IsPointerPressed(PaperMouseBtn btn)

return

bool

true only on the first frame the button goes down.

IsPointerReleased

public bool IsPointerReleased(PaperMouseBtn btn)

return

bool

true only on the frame the button goes up.

IsPointerHeld

public bool IsPointerHeld(PaperMouseBtn btn, float holdDuration = 0.5f)

holdDuration

float

default:"0.5"

Minimum seconds the button must have been held.

return

bool

true when btn has been down for at least holdDuration seconds.

IsPointerDoubleClick

public bool IsPointerDoubleClick(PaperMouseBtn btn)

Returns true when btn is pressed within 0.25 s of its previous release and the squared distance from the release position is less than 2 (approximately 1.4 logical pixels).

return

bool

true on the double-click frame.

GetPointerClickPos

public Float2 GetPointerClickPos(PaperMouseBtn btn)

return

Float2

The pointer position recorded when btn was last pressed.

IsPointerOverRect

public bool IsPointerOverRect(float x, float y, float width, float height)

Simple AABB hit test against the current pointer position.

float

required

Rect left edge in logical pixels.

float

required

Rect top edge in logical pixels.

width

float

required

Rect width.

height

float

required

Rect height.

return

bool

true if the pointer is inside the rectangle.

Pointer Position Properties

PointerPos

Float2

Current pointer position in logical pixels. Writable — setting this also fires the OnPointerPosSet event.

PreviousPointerPos

Float2

Pointer position at the end of the previous frame.

PointerDelta

Float2

PointerPos - PreviousPointerPos. Zero when the pointer has not moved.

IsPointerMoving

bool

true when PointerDelta has non-zero length squared.

PointerWheel

float

Scroll wheel delta for the current frame. Reset to 0 at the end of each EndFrame.

LastButtonPressed

PaperMouseBtn

The button most recently updated by SetPointerState.

Keyboard Capture

CaptureKeyboard

public void CaptureKeyboard()

Signals that the current element wants exclusive keyboard input for this frame. Sets WantsCaptureKeyboard to true at the end of the frame. Your host can read WantsCaptureKeyboard after EndFrame to suppress its own key handling.

WantsCaptureKeyboard

public bool WantsCaptureKeyboard { get; }

true after EndFrame if any element called CaptureKeyboard this frame. Read this in your host to prevent passing keyboard events to game logic while a text field is focused.

Auto-Repeat Configuration

Auto-repeat makes held keys fire repeated IsKeyPressedOrRepeating pulses, matching system key-repeat behaviour.

KeyAutoRepeatEnabled

bool

Enables or disables key auto-repeat globally. Default true.

AutoRepeatDelay

float

Seconds a key must be held before auto-repeat begins. Default 0.8 s. Minimum safe value is 0.1 s.

AutoRepeatRate

float

Seconds between repeat pulses once repeating has started. Default 0.05 s (20 repeats/s). Minimum is 0.01 s (100 repeats/s).

Clipboard

Paper decouples clipboard access behind an interface to remain platform-agnostic.

IClipboardHandler

public interface IClipboardHandler
{
    string GetClipboardText();
    void SetClipboardText(string text);
}

Implement this interface in your host project and register it with SetClipboardHandler.

SetClipboardHandler

public void SetClipboardHandler(IClipboardHandler handler)

handler

IClipboardHandler

required

Your platform clipboard implementation. Must not be null.

GetClipboard

public string GetClipboard()

Calls IClipboardHandler.GetClipboardText(). Logs a warning and returns "" if no handler is registered.

return

string

Current clipboard text.

SetClipboard

public void SetClipboard(string text)

Calls IClipboardHandler.SetClipboardText(text). Logs a warning if no handler is registered.

text

string

required

Text to place on the system clipboard.

Cursor Visibility

SetCursorVisibility

public void SetCursorVisibility(bool visible)

Fires the OnCursorVisibilitySet event with visible. Hook this event in your host to show or hide the OS cursor.

visible

bool

required

true to show the cursor; false to hide it.

Events

OnPointerPosSet

event Action<Float2>

Fired whenever PointerPos is set (via the property setter). Passes the new position.

OnCursorVisibilitySet

event Action<bool>

Fired whenever SetCursorVisibility is called. Passes the requested visibility.

PaperKey Enum

All keyboard keys supported by Paper. Pass values from this enum to SetKeyState and all IsKey* query methods.

Group	Values
Alpha	`A`–`Z`
Digits	`Num0`–`Num9`
Function	`F1`–`F12`
Control	`Enter`, `Escape`, `Backspace`, `Tab`, `Space`
Punctuation	`Minus`, `Equals`, `LeftBracket`, `RightBracket`, `Backslash`, `Semicolon`, `Apostrophe`, `Grave`, `Comma`, `Period`, `Slash`
System	`CapsLock`, `PrintScreen`, `ScrollLock`, `Pause`, `Insert`, `Home`, `PageUp`, `Delete`, `End`, `PageDown`
Arrows	`Right`, `Left`, `Down`, `Up`
Numpad	`NumLock`, `KeypadDivide`, `KeypadMultiply`, `KeypadMinus`, `KeypadPlus`, `KeypadEnter`, `KeypadEquals`, `Keypad0`–`Keypad9`, `KeypadDecimal`
Modifiers	`LeftControl`, `LeftShift`, `LeftAlt`, `LeftSuper`, `RightControl`, `RightShift`, `RightAlt`, `RightSuper`
Media	`AudioNext`, `AudioPrevious`, `AudioStop`, `AudioPlay`, `AudioMute`
Application	`Application`, `Menu`, `Select`, `Help`
Sentinel	`Unknown = 0`

PaperMouseBtn Enum

Value	Meaning
`Unknown`	Sentinel / unset
`Left`	Primary / left button
`Middle`	Middle / scroll-wheel button
`Right`	Secondary / right button
`Button4`–`Button8`	Extra buttons on extended mice

Example: Host Wiring

// In your host's event loop (e.g., SDL2, GLFW, Win32):

// Movement
paper.SetPointerPosition(mouseEvent.X, mouseEvent.Y);

// Button down
paper.SetPointerState(PaperMouseBtn.Left, mouseEvent.X, mouseEvent.Y,
    isPointerBtnDown: true, isPointerMove: false);

// Scroll
paper.SetPointerWheel(scrollEvent.DeltaY);

// Key down
paper.SetKeyState(PaperKey.A, isKeyDown: true);

// Text input (produced by the IME / OS key translation)
paper.AddInputCharacter("a");

// --- then --- 
paper.BeginFrame(deltaTime);
// ... UI code ...
paper.EndFrame();

// Read capture flags after EndFrame
if (paper.WantsCaptureKeyboard)
    SuppressGameKeyHandling();

Paper Class

Element Builder

Types & Enums

Documentation Index

​Input Feed Methods

​SetPointerPosition

​SetPointerState

​SetPointerWheel

​AddInputCharacter

​PushInputText

​SetKeyState

​ClearInput

​Keyboard Query Methods

​IsKeyDown

​IsKeyUp

​IsKeyPressed

​IsKeyReleased

​IsKeyHeld

​IsKeyRepeating

​IsKeyPressedOrRepeating

​LastKeyPressed

​Mouse / Pointer Query Methods

​IsPointerDown

​IsPointerUp

​IsPointerPressed

​IsPointerReleased

​IsPointerHeld

​IsPointerDoubleClick

​GetPointerClickPos

​IsPointerOverRect

​Pointer Position Properties

​Keyboard Capture

​CaptureKeyboard

​WantsCaptureKeyboard

​Auto-Repeat Configuration

​Clipboard

​IClipboardHandler

​SetClipboardHandler

​GetClipboard

​SetClipboard

​Cursor Visibility

​SetCursorVisibility

​Events

​PaperKey Enum

​PaperMouseBtn Enum

​Example: Host Wiring

Build docs developers (and LLMs) love

Input Feed Methods

SetPointerPosition

SetPointerState

SetPointerWheel

AddInputCharacter

PushInputText

SetKeyState

ClearInput

Keyboard Query Methods

IsKeyDown

IsKeyUp

IsKeyPressed

IsKeyReleased

IsKeyHeld

IsKeyRepeating

IsKeyPressedOrRepeating

LastKeyPressed

Mouse / Pointer Query Methods

IsPointerDown

IsPointerUp

IsPointerPressed

IsPointerReleased

IsPointerHeld

IsPointerDoubleClick

GetPointerClickPos

IsPointerOverRect

Pointer Position Properties

Keyboard Capture

CaptureKeyboard

WantsCaptureKeyboard

Auto-Repeat Configuration

Clipboard

IClipboardHandler

SetClipboardHandler

GetClipboard

SetClipboard

Cursor Visibility

SetCursorVisibility

Events

PaperKey Enum

PaperMouseBtn Enum

Example: Host Wiring