event

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 21, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package event provides input event types for the gogpu/ui toolkit.

This package defines the core event types used for handling user input throughout the UI framework: mouse events, keyboard events, focus events, wheel (scroll) events, and modifier key states.

Event Types

  • Event: Base interface implemented by all event types
  • MouseEvent: Mouse button presses, releases, moves, enter/leave
  • KeyEvent: Keyboard key presses, releases, and repeats
  • FocusEvent: Widget focus gained or lost
  • WheelEvent: Mouse wheel scroll events

Event Flow

Events flow through the widget tree from root to target:

  1. Event is received from the platform layer
  2. Event is dispatched to the root widget
  3. Root widget propagates event to children
  4. Target widget handles event and may mark it as handled
  5. If not handled, event bubbles back up to ancestors

Modifiers

The Modifiers type is a bitmask representing which modifier keys (Shift, Ctrl, Alt, Super/Cmd) are held during an event: 

if event.Modifiers().Has(ModCtrl | ModShift) {
    // Ctrl+Shift combination
}

Usage Example 

func (w *MyWidget) HandleEvent(e event.Event) bool {
    switch ev := e.(type) {
    case *event.MouseEvent:
        if ev.Type == event.MousePress && ev.Button == event.ButtonLeft {
            w.onClick(ev.Position)
            ev.SetHandled()
            return true
        }
    case *event.KeyEvent:
        if ev.Type == event.KeyPress && ev.Key == event.KeyEnter {
            w.onSubmit()
            ev.SetHandled()
            return true
        }
    }
    return false
}

Thread Safety

Event objects are NOT safe for concurrent access. Events are processed sequentially on the main/UI thread. Do not store events or access them from other goroutines.

Design Principles

  • All coordinates use float32 for GPU compatibility
  • Positions are represented using geometry.Point
  • Events are mutable (handled state can be changed)
  • Time stamps use time.Time for precision

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Base 

type Base struct {
	// contains filtered or unexported fields
}

Base provides common fields and methods for all event types.

Embed this struct in concrete event types to inherit the base implementation. All concrete event types must use pointer receivers to allow SetHandled to work.

func NewBase 

func NewBase(eventType Type, mods Modifiers) Base

NewBase creates a new Base event with the given type and current time.

func NewBaseWithTime 

func NewBaseWithTime(eventType Type, t time.Time, mods Modifiers) Base

NewBaseWithTime creates a new Base event with the given type and timestamp.

func (*Base) Handled 

func (b *Base) Handled() bool

Handled returns true if the event has been handled.

func (*Base) Modifiers 

func (b *Base) Modifiers() Modifiers

Modifiers returns the modifier keys held when the event occurred.

func (*Base) SetHandled 

func (b *Base) SetHandled()

SetHandled marks the event as handled, preventing further propagation.

func (*Base) Time 

func (b *Base) Time() time.Time

Time returns when the event occurred.

func (*Base) Type 

func (b *Base) Type() Type

Type returns the category of this event.

type Button 

type Button uint8

Button represents a mouse button. 

const (
	// ButtonNone indicates no button (used for move events).
	ButtonNone Button = iota

	// ButtonLeft is the primary mouse button.
	ButtonLeft

	// ButtonRight is the secondary mouse button.
	ButtonRight

	// ButtonMiddle is the middle mouse button (scroll wheel click).
	ButtonMiddle

	// ButtonX1 is the first extended button (back button).
	ButtonX1

	// ButtonX2 is the second extended button (forward button).
	ButtonX2
)

Mouse button constants.

func (Button) String 

func (b Button) String() string

String returns a human-readable name for the button.

type ButtonState 

type ButtonState uint8

ButtonState represents which mouse buttons are currently pressed. 

const (
	// ButtonStateLeft indicates the left button is pressed.
	ButtonStateLeft ButtonState = 1 << iota

	// ButtonStateRight indicates the right button is pressed.
	ButtonStateRight

	// ButtonStateMiddle indicates the middle button is pressed.
	ButtonStateMiddle

	// ButtonStateX1 indicates the X1 button is pressed.
	ButtonStateX1

	// ButtonStateX2 indicates the X2 button is pressed.
	ButtonStateX2
)

Button state bit flags.

func (ButtonState) AnyPressed 

func (s ButtonState) AnyPressed() bool

AnyPressed returns true if any button is pressed.

func (ButtonState) Has 

func (s ButtonState) Has(state ButtonState) bool

Has returns true if the specified button is pressed.

func (ButtonState) IsLeftPressed 

func (s ButtonState) IsLeftPressed() bool

IsLeftPressed returns true if the left button is pressed.

func (ButtonState) IsMiddlePressed 

func (s ButtonState) IsMiddlePressed() bool

IsMiddlePressed returns true if the middle button is pressed.

func (ButtonState) IsRightPressed 

func (s ButtonState) IsRightPressed() bool

IsRightPressed returns true if the right button is pressed.

func (ButtonState) IsX1Pressed 

func (s ButtonState) IsX1Pressed() bool

IsX1Pressed returns true if the X1 button is pressed.

func (ButtonState) IsX2Pressed 

func (s ButtonState) IsX2Pressed() bool

IsX2Pressed returns true if the X2 button is pressed.

type Event 

type Event interface {
	// Type returns the category of this event.
	Type() Type

	// Time returns when the event occurred.
	Time() time.Time

	// Handled returns true if the event has been handled.
	Handled() bool

	// SetHandled marks the event as handled, preventing further propagation.
	SetHandled()

	// Modifiers returns the modifier keys held when the event occurred.
	Modifiers() Modifiers
}

Event is the interface implemented by all event types.

Events carry information about user input and can be marked as handled to prevent further propagation through the widget tree.

type FocusEvent 

type FocusEvent struct {
	Base

	// FocusType is the specific type of focus event.
	FocusType FocusEventType
}

FocusEvent represents a focus change event.

Focus events are sent when a widget gains or loses keyboard focus. Only one widget can have focus at a time within a window.

func NewFocusEvent 

func NewFocusEvent(focusType FocusEventType) *FocusEvent

NewFocusEvent creates a new focus event with the current time.

func NewFocusEventWithTime 

func NewFocusEventWithTime(focusType FocusEventType, t time.Time) *FocusEvent

NewFocusEventWithTime creates a new focus event with a specific timestamp.

func (*FocusEvent) IsGained 

func (e *FocusEvent) IsGained() bool

IsGained returns true if this is a focus gained event.

func (*FocusEvent) IsLost 

func (e *FocusEvent) IsLost() bool

IsLost returns true if this is a focus lost event.

func (*FocusEvent) String 

func (e *FocusEvent) String() string

String returns a human-readable representation of the event.

type FocusEventType 

type FocusEventType uint8

FocusEventType represents the specific type of focus event. 

const (
	// FocusGained indicates the widget gained keyboard focus.
	FocusGained FocusEventType = iota + 1

	// FocusLost indicates the widget lost keyboard focus.
	FocusLost
)

Focus event type constants.

func (FocusEventType) String 

func (t FocusEventType) String() string

String returns a human-readable name for the focus event type.

type Key 

type Key uint16

Key represents a keyboard key code.

Key codes represent physical or virtual keys, not characters. Use Rune for the character that was typed. 

const (
	KeyA Key = iota + 1
	KeyB
	KeyC
	KeyD
	KeyE
	KeyF
	KeyG
	KeyH
	KeyI
	KeyJ
	KeyK
	KeyL
	KeyM
	KeyN
	KeyO
	KeyP
	KeyQ
	KeyR
	KeyS
	KeyT
	KeyU
	KeyV
	KeyW
	KeyX
	KeyY
	KeyZ
)

Letter key constants (A-Z). 

const (
	Key0 Key = iota + 100
	Key1
	Key2
	Key3
	Key4
	Key5
	Key6
	Key7
	Key8
	Key9
)

Number key constants (0-9). 

const (
	KeyF1 Key = iota + 200
	KeyF2
	KeyF3
	KeyF4
	KeyF5
	KeyF6
	KeyF7
	KeyF8
	KeyF9
	KeyF10
	KeyF11
	KeyF12
	KeyF13
	KeyF14
	KeyF15
	KeyF16
	KeyF17
	KeyF18
	KeyF19
	KeyF20
	KeyF21
	KeyF22
	KeyF23
	KeyF24
)

Function key constants (F1-F24). 

const (
	KeyUp Key = iota + 300
	KeyDown
	KeyLeft
	KeyRight
	KeyHome
	KeyEnd
	KeyPageUp
	KeyPageDown
)

Navigation key constants. 

const (
	KeyEnter Key = iota + 400
	KeyTab
	KeyBackspace
	KeyDelete
	KeyInsert
	KeyEscape
	KeySpace
)

Editing key constants. 

const (
	KeyLeftShift Key = iota + 500
	KeyRightShift
	KeyLeftCtrl
	KeyRightCtrl
	KeyLeftAlt
	KeyRightAlt
	KeyLeftSuper
	KeyRightSuper
	KeyCapsLock
	KeyNumLock
	KeyScrollLock
)

Modifier key constants. 

const (
	KeyNumpad0 Key = iota + 600
	KeyNumpad1
	KeyNumpad2
	KeyNumpad3
	KeyNumpad4
	KeyNumpad5
	KeyNumpad6
	KeyNumpad7
	KeyNumpad8
	KeyNumpad9
	KeyNumpadDecimal
	KeyNumpadEnter
	KeyNumpadAdd
	KeyNumpadSubtract
	KeyNumpadMultiply
	KeyNumpadDivide
)

Numpad key constants. 

const (
	KeyMinus Key = iota + 700
	KeyEqual
	KeyLeftBracket
	KeyRightBracket
	KeyBackslash
	KeySemicolon
	KeyApostrophe
	KeyGrave
	KeyComma
	KeyPeriod
	KeySlash
)

Symbol and punctuation key constants. 

const (
	KeyPrintScreen Key = iota + 800
	KeyPause
	KeyMenu
	KeyMute
	KeyVolumeUp
	KeyVolumeDown
	KeyMediaPlay
	KeyMediaStop
	KeyMediaNext
	KeyMediaPrev
)

Media and system key constants. 

const (
	// KeyUnknown represents an unknown or unmapped key.
	KeyUnknown Key = 0
)

Special key constant.

func (Key) IsDigit 

func (k Key) IsDigit() bool

IsDigit returns true if the key is a digit key (0-9).

func (Key) IsFunction 

func (k Key) IsFunction() bool

IsFunction returns true if the key is a function key (F1-F24).

func (Key) IsLetter 

func (k Key) IsLetter() bool

IsLetter returns true if the key is a letter key (A-Z).

func (Key) IsModifier 

func (k Key) IsModifier() bool

IsModifier returns true if the key is a modifier key.

func (Key) IsNavigation 

func (k Key) IsNavigation() bool

IsNavigation returns true if the key is a navigation key.

func (Key) IsNumpad 

func (k Key) IsNumpad() bool

IsNumpad returns true if the key is a numpad key.

func (Key) String 

func (k Key) String() string

String returns a human-readable name for the key.

type KeyEvent 

type KeyEvent struct {
	Base

	// KeyType is the specific type of key event.
	KeyType KeyEventType

	// Key is the key code that was pressed/released.
	Key Key

	// Rune is the character that was typed, or 0 if not applicable.
	// For example, pressing 'A' with Shift produces Rune='A'.
	// Pressing 'F1' produces Rune=0.
	Rune rune

	// ScanCode is the platform-specific scan code.
	ScanCode uint32
}

KeyEvent represents a keyboard input event.

Key represents the physical key pressed. Rune contains the character that was typed (if applicable).

func NewKeyEvent 

func NewKeyEvent(keyType KeyEventType, key Key, r rune, mods Modifiers) *KeyEvent

NewKeyEvent creates a new key event with the current time.

func NewKeyEventWithTime 

func NewKeyEventWithTime(keyType KeyEventType, key Key, r rune, mods Modifiers, t time.Time) *KeyEvent

NewKeyEventWithTime creates a new key event with a specific timestamp.

func (*KeyEvent) HasRune 

func (e *KeyEvent) HasRune() bool

HasRune returns true if a character was typed.

func (*KeyEvent) IsAlt 

func (e *KeyEvent) IsAlt() bool

IsAlt returns true if Alt modifier is held.

func (*KeyEvent) IsCtrl 

func (e *KeyEvent) IsCtrl() bool

IsCtrl returns true if Ctrl modifier is held.

func (*KeyEvent) IsPress 

func (e *KeyEvent) IsPress() bool

IsPress returns true if this is a key press event.

func (*KeyEvent) IsRelease 

func (e *KeyEvent) IsRelease() bool

IsRelease returns true if this is a key release event.

func (*KeyEvent) IsRepeat 

func (e *KeyEvent) IsRepeat() bool

IsRepeat returns true if this is a key repeat event.

func (*KeyEvent) IsShift 

func (e *KeyEvent) IsShift() bool

IsShift returns true if Shift modifier is held.

func (*KeyEvent) IsSuper 

func (e *KeyEvent) IsSuper() bool

IsSuper returns true if Super modifier is held.

func (*KeyEvent) String 

func (e *KeyEvent) String() string

String returns a human-readable representation of the event.

type KeyEventType 

type KeyEventType uint8

KeyEventType represents the specific type of keyboard event. 

const (
	// KeyPress indicates a key was pressed.
	KeyPress KeyEventType = iota + 1

	// KeyRelease indicates a key was released.
	KeyRelease

	// KeyRepeat indicates a key is being held and auto-repeating.
	KeyRepeat
)

Keyboard event type constants.

func (KeyEventType) String 

func (t KeyEventType) String() string

String returns a human-readable name for the key event type.

type Modifiers 

type Modifiers uint8

Modifiers represents a bitmask of modifier keys held during an event.

Multiple modifiers can be combined using bitwise OR: 

mods := ModCtrl | ModShift

const (
	// ModNone indicates no modifier keys are pressed.
	ModNone Modifiers = 0

	// ModShift indicates the Shift key is pressed.
	ModShift Modifiers = 1 << iota

	// ModCtrl indicates the Control key is pressed.
	ModCtrl

	// ModAlt indicates the Alt key (Option on macOS) is pressed.
	ModAlt

	// ModSuper indicates the Super key (Windows key, Cmd on macOS) is pressed.
	ModSuper

	// ModCapsLock indicates Caps Lock is active.
	ModCapsLock

	// ModNumLock indicates Num Lock is active.
	ModNumLock
)

Modifier key constants.

func (Modifiers) Has 

func (m Modifiers) Has(mod Modifiers) bool

Has returns true if all the specified modifier bits are set.

Example: 

if mods.Has(ModCtrl | ModShift) {
    // Both Ctrl and Shift are pressed
}

func (Modifiers) HasAny 

func (m Modifiers) HasAny(mod Modifiers) bool

HasAny returns true if any of the specified modifier bits are set.

Example: 

if mods.HasAny(ModCtrl | ModSuper) {
    // Either Ctrl or Super is pressed
}

func (Modifiers) IsAlt 

func (m Modifiers) IsAlt() bool

IsAlt returns true if the Alt modifier is set.

func (Modifiers) IsCapsLock 

func (m Modifiers) IsCapsLock() bool

IsCapsLock returns true if Caps Lock is active.

func (Modifiers) IsCtrl 

func (m Modifiers) IsCtrl() bool

IsCtrl returns true if the Control modifier is set.

func (Modifiers) IsNumLock 

func (m Modifiers) IsNumLock() bool

IsNumLock returns true if Num Lock is active.

func (Modifiers) IsShift 

func (m Modifiers) IsShift() bool

IsShift returns true if the Shift modifier is set.

func (Modifiers) IsSuper 

func (m Modifiers) IsSuper() bool

IsSuper returns true if the Super modifier is set.

func (Modifiers) String 

func (m Modifiers) String() string

String returns a human-readable representation of the modifiers.

Example: 

(ModCtrl | ModShift).String() // "Ctrl+Shift"

func (Modifiers) With 

func (m Modifiers) With(mod Modifiers) Modifiers

With returns a new Modifiers value with the specified modifier added.

func (Modifiers) Without 

func (m Modifiers) Without(mod Modifiers) Modifiers

Without returns a new Modifiers value with the specified modifier removed.

type MouseEvent 

type MouseEvent struct {
	Base

	// MouseType is the specific type of mouse event.
	MouseType MouseEventType

	// Button is the button involved in press/release events.
	Button Button

	// Buttons is the state of all mouse buttons.
	Buttons ButtonState

	// Position is the mouse position relative to the widget.
	Position geometry.Point

	// GlobalPosition is the mouse position in screen coordinates.
	GlobalPosition geometry.Point

	// ClickCount is the number of consecutive clicks (1 for single, 2 for double).
	ClickCount int
}

MouseEvent represents a mouse input event.

Position is relative to the widget receiving the event. GlobalPosition is the position in screen coordinates.

func NewMouseEvent 

func NewMouseEvent(
	mouseType MouseEventType,
	button Button,
	buttons ButtonState,
	position geometry.Point,
	globalPosition geometry.Point,
	mods Modifiers,
) *MouseEvent

NewMouseEvent creates a new mouse event with the current time.

func NewMouseEventWithTime 

func NewMouseEventWithTime(
	mouseType MouseEventType,
	button Button,
	buttons ButtonState,
	position geometry.Point,
	globalPosition geometry.Point,
	mods Modifiers,
	t time.Time,
) *MouseEvent

NewMouseEventWithTime creates a new mouse event with a specific timestamp.

func (*MouseEvent) IsDoubleClick 

func (e *MouseEvent) IsDoubleClick() bool

IsDoubleClick returns true if this is a double-click event.

func (*MouseEvent) IsDrag 

func (e *MouseEvent) IsDrag() bool

IsDrag returns true if this is a drag event.

func (*MouseEvent) IsEnter 

func (e *MouseEvent) IsEnter() bool

IsEnter returns true if this is a mouse enter event.

func (*MouseEvent) IsLeave 

func (e *MouseEvent) IsLeave() bool

IsLeave returns true if this is a mouse leave event.

func (*MouseEvent) IsLeftButton 

func (e *MouseEvent) IsLeftButton() bool

IsLeftButton returns true if the left button is involved.

func (*MouseEvent) IsMiddleButton 

func (e *MouseEvent) IsMiddleButton() bool

IsMiddleButton returns true if the middle button is involved.

func (*MouseEvent) IsMove 

func (e *MouseEvent) IsMove() bool

IsMove returns true if this is a mouse move event.

func (*MouseEvent) IsPress 

func (e *MouseEvent) IsPress() bool

IsPress returns true if this is a button press event.

func (*MouseEvent) IsRelease 

func (e *MouseEvent) IsRelease() bool

IsRelease returns true if this is a button release event.

func (*MouseEvent) IsRightButton 

func (e *MouseEvent) IsRightButton() bool

IsRightButton returns true if the right button is involved.

func (*MouseEvent) String 

func (e *MouseEvent) String() string

String returns a human-readable representation of the event.

type MouseEventType 

type MouseEventType uint8

MouseEventType represents the specific type of mouse event. 

const (
	// MousePress indicates a mouse button was pressed.
	MousePress MouseEventType = iota + 1

	// MouseRelease indicates a mouse button was released.
	MouseRelease

	// MouseMove indicates the mouse pointer moved.
	MouseMove

	// MouseEnter indicates the mouse pointer entered a widget's bounds.
	MouseEnter

	// MouseLeave indicates the mouse pointer left a widget's bounds.
	MouseLeave

	// MouseDrag indicates the mouse is moving while a button is held.
	MouseDrag

	// MouseDoubleClick indicates a double-click occurred.
	MouseDoubleClick
)

Mouse event type constants.

func (MouseEventType) String 

func (t MouseEventType) String() string

String returns a human-readable name for the mouse event type.

type Type 

type Type uint8

Type represents the category of an event. 

const (
	// TypeMouse represents mouse button and movement events.
	TypeMouse Type = iota + 1

	// TypeKey represents keyboard events.
	TypeKey

	// TypeFocus represents focus change events.
	TypeFocus

	// TypeWheel represents mouse wheel scroll events.
	TypeWheel

	// TypeTouch represents touch screen events.
	TypeTouch

	// TypeText represents text input events.
	TypeText

	// TypeDrop represents drag-and-drop events.
	TypeDrop

	// TypeResize represents window/widget resize events.
	TypeResize
)

Event type constants.

func (Type) String 

func (t Type) String() string

String returns a human-readable name for the event type.

type WheelEvent 

type WheelEvent struct {
	Base

	// Delta is the scroll amount (X for horizontal, Y for vertical).
	Delta geometry.Point

	// Position is the mouse position relative to the widget.
	Position geometry.Point

	// GlobalPosition is the mouse position in screen coordinates.
	GlobalPosition geometry.Point
}

WheelEvent represents a mouse wheel scroll event.

Delta contains the scroll amount in both directions. The sign convention matches the gogpu platform:

  • Positive Delta.Y means scrolling down (content moves up)
  • Negative Delta.Y means scrolling up (content moves down)
  • Positive Delta.X means scrolling right
  • Negative Delta.X means scrolling left

The delta values are typically in "lines" for discrete scroll wheels, or pixels for smooth scrolling (e.g., trackpads).

func NewWheelEvent 

func NewWheelEvent(
	delta geometry.Point,
	position geometry.Point,
	globalPosition geometry.Point,
	mods Modifiers,
) *WheelEvent

NewWheelEvent creates a new wheel event with the current time.

func NewWheelEventWithTime 

func NewWheelEventWithTime(
	delta geometry.Point,
	position geometry.Point,
	globalPosition geometry.Point,
	mods Modifiers,
	t time.Time,
) *WheelEvent

NewWheelEventWithTime creates a new wheel event with a specific timestamp.

func (*WheelEvent) DeltaX 

func (e *WheelEvent) DeltaX() float32

DeltaX returns the horizontal scroll amount.

func (*WheelEvent) DeltaY 

func (e *WheelEvent) DeltaY() float32

DeltaY returns the vertical scroll amount.

func (*WheelEvent) IsHorizontal 

func (e *WheelEvent) IsHorizontal() bool

IsHorizontal returns true if there is any horizontal scrolling.

func (*WheelEvent) IsScrollDown 

func (e *WheelEvent) IsScrollDown() bool

IsScrollDown returns true if scrolling down (negative Y delta).

func (*WheelEvent) IsScrollLeft 

func (e *WheelEvent) IsScrollLeft() bool

IsScrollLeft returns true if scrolling left (negative X delta).

func (*WheelEvent) IsScrollRight 

func (e *WheelEvent) IsScrollRight() bool

IsScrollRight returns true if scrolling right (positive X delta).

func (*WheelEvent) IsScrollUp 

func (e *WheelEvent) IsScrollUp() bool

IsScrollUp returns true if scrolling up (positive Y delta).

func (*WheelEvent) IsVertical 

func (e *WheelEvent) IsVertical() bool

IsVertical returns true if there is any vertical scrolling.

func (*WheelEvent) String 

func (e *WheelEvent) String() string

String returns a human-readable representation of the event.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.