event

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2026 License: BSD-3-Clause Imports: 1 Imported by: 0

Documentation

Overview

Package event defines input event types and behavioral interfaces for canvas objects that respond to user interaction.

This package has no dependency on the root bellui package, making it safe to import from any level of the framework without circular dependency. 

import "github.com/belluikit/bellui/event"

type MyButton struct { widget.BaseWidget }
func (b *MyButton) Tapped(ev *event.PointEvent) { /* handle tap */ }

Index

Constants

View Source 
const KeyModifierShortcutDefault = KeyModifierControl

KeyModifierShortcutDefault is the default key modifier for shortcuts (Control or Command).

Since: 1.0

Variables

This section is empty.

Functions

This section is empty.

Types

type Activatable 

type Activatable interface {
	Focusable
	// ActivatedByKey reports whether the given key event activates this object
	// (rather than being consumed as navigation or text). The driver calls it for
	// the focused object on each key event and, when it returns true, fires the
	// activation signal just before forwarding the key to [Focusable.TypedKey].
	ActivatedByKey(*KeyEvent) bool
}

Activatable is an optional capability of a Focusable control that a keyboard key (typically Space or Enter) activates the same way a pointer tap does — a button, checkbox, switch, menu item, list row, etc. It lets the driver fire the central activation signal (core.NotifyActivation) for keyboard activation, giving accessibility/analytics parity with the pointer-tap path (pre-rebrand tracker #700) without the driver having to guess which keys mean "activate" versus navigation or text input.

Focusables that consume Space/Enter as content (text editors) or navigation do not implement it. Because it is a capability on the focused object, a widget that embeds an activatable base (for example one embedding widget.Button) inherits it automatically, and the driver reports the outer focused object.

Since: 1.0

type Composable 

type Composable interface {
	Focusable
	// Compose sets or replaces the inline preedit text shown at the caret. It
	// must not alter the committed value, fire change callbacks, or affect undo.
	Compose(*PreeditEvent)
	// ComposeCommit finalizes the composition, inserting text as if it had been
	// typed (updating the value, undo history and change callbacks).
	ComposeCommit(string)
	// ComposeCancel discards any in-progress composition without committing.
	ComposeCancel()
}

Composable is an optional capability of a Focusable that supports IME (input method editor) composition, allowing CJK and other users to enter text via a preedit/candidate workflow. Drivers detect support via a type assertion on the focused object.

Since: 1.0

type DoubleTappable 

type DoubleTappable interface {
	DoubleTapped(*PointEvent)
}

DoubleTappable describes any CanvasObject that can be double tapped.

type DragEvent 

type DragEvent struct {
	PointEvent
	Dragged geo.Delta
}

DragEvent defines the parameters of a pointer or other drag event.

type Draggable 

type Draggable interface {
	Dragged(*DragEvent)
	DragEnd()
}

Draggable indicates that a CanvasObject can be dragged.

type EscapeDismissible 

type EscapeDismissible interface {
	// DismissOnEscape closes this overlay and reports whether it did. An
	// overlay that owns its own lifetime — a snackbar counting down to its own
	// dismissal — returns false and leaves the key to whatever is beneath it.
	DismissOnEscape() bool
}

EscapeDismissible describes an overlay that closes when the user presses Escape. Pop-ups, menus and dialogs implement it, so backing out of whatever is on top works everywhere without each one wiring up its own key handler.

Overlays are asked innermost-first. An implementing overlay that declines passes the key to the overlay beneath it; the first to report true consumes the key. An overlay that does not implement the interface ends the search with the key unconsumed — it is assumed to handle Escape through the normal focus path, the way menus and completion lists do.

Since: 1.0

type EscapeHandler 

type EscapeHandler interface {
	HandlesEscape() bool
}

EscapeHandler describes a Focusable that wants the Escape key for itself rather than letting it close the surrounding pop-up or dialog.

Escape means "back out of the innermost thing", and a widget can be that innermost thing without being an overlay: a text field mid-IME-composition, a cell being edited in place, a picker holding a half-typed value. Such a widget reports true while it is in that state and false the rest of the time, so Escape falls through to the dialog around it once there is nothing left to back out of.

A focusable that does not implement this never blocks the key.

Since: 1.0

type Focusable 

type Focusable interface {
	FocusGained()
	FocusLost()
	TypedRune(rune)
	TypedKey(*KeyEvent)
}

Focusable describes any CanvasObject that can respond to being focused.

type HardwareKey 

type HardwareKey struct {
	// ScanCode represents a hardware ID for (normally desktop) keyboard events.
	ScanCode int
}

HardwareKey contains information associated with physical key events.

type HoverEvent 

type HoverEvent struct {
	PointEvent
}

HoverEvent describes a pointer hovering over or entering/leaving a canvas object. Unlike desktop.MouseEvent it carries only position information — no button or modifier state.

type Hoverable 

type Hoverable interface {
	// HoverIn is called when a pointer enters the element.
	HoverIn(*HoverEvent)
	// HoverMoved is called when a pointer moves within the element.
	HoverMoved(*HoverEvent)
	// HoverOut is called when a pointer leaves the element.
	HoverOut()
}

Hoverable describes any CanvasObject that wants to know when a pointer hovers over it.

type KeyEvent 

type KeyEvent struct {
	// Name describes the keyboard event that is consistent across platforms.
	Name KeyName
	// Physical is a platform specific field that reports hardware information.
	Physical HardwareKey
	// Modifier reports the modifier keys held when the event was generated,
	// as a [KeyModifier] bitmask. The zero value means no modifiers. It lets
	// key handlers (TypedKey, Canvas.SetOnTypedKey) distinguish e.g. Shift+F11
	// from F11 without registering a shortcut. The desktop and web drivers
	// populate it from the native key event; the mobile driver reports what
	// the platform delivers for hardware keyboards; drivers without modifier
	// information leave it zero.
	//
	// Note that on desktop, Control/Alt/Super combinations are routed to the
	// shortcut system instead of TypedKey (unchanged behavior) — only
	// unmodified and Shift-modified keys reach TypedKey there. All
	// combinations are visible with modifiers on the KeyDown/KeyUp events of
	// a widget implementing the desktop driver's Keyable. For the window-wide
	// modifier state outside a key event, see the desktop driver's
	// KeyModifierDriver interface.
	//
	// Since: 1.0
	Modifier KeyModifier
}

KeyEvent describes a keyboard input event.

type KeyModifier 

type KeyModifier int

KeyModifier represents any modifier key (shift etc.) being pressed with a key. 

const (
	KeyModifierShift KeyModifier = 1 << iota
	KeyModifierControl
	KeyModifierAlt
	KeyModifierSuper
)

type KeyName 

type KeyName string

KeyName represents the name of a key that has been pressed. 

const (
	KeyEscape       KeyName = "Escape"
	KeyReturn       KeyName = "Return"
	KeyTab          KeyName = "Tab"
	KeyBackspace    KeyName = "BackSpace"
	KeyInsert       KeyName = "Insert"
	KeyDelete       KeyName = "Delete"
	KeyRight        KeyName = "Right"
	KeyLeft         KeyName = "Left"
	KeyDown         KeyName = "Down"
	KeyUp           KeyName = "Up"
	KeyPageUp       KeyName = "Prior"
	KeyPageDown     KeyName = "Next"
	KeyHome         KeyName = "Home"
	KeyEnd          KeyName = "End"
	KeyF1           KeyName = "F1"
	KeyF2           KeyName = "F2"
	KeyF3           KeyName = "F3"
	KeyF4           KeyName = "F4"
	KeyF5           KeyName = "F5"
	KeyF6           KeyName = "F6"
	KeyF7           KeyName = "F7"
	KeyF8           KeyName = "F8"
	KeyF9           KeyName = "F9"
	KeyF10          KeyName = "F10"
	KeyF11          KeyName = "F11"
	KeyF12          KeyName = "F12"
	KeyEnter        KeyName = "KP_Enter"
	Key0            KeyName = "0"
	Key1            KeyName = "1"
	Key2            KeyName = "2"
	Key3            KeyName = "3"
	Key4            KeyName = "4"
	Key5            KeyName = "5"
	Key6            KeyName = "6"
	Key7            KeyName = "7"
	Key8            KeyName = "8"
	Key9            KeyName = "9"
	KeyA            KeyName = "A"
	KeyB            KeyName = "B"
	KeyC            KeyName = "C"
	KeyD            KeyName = "D"
	KeyE            KeyName = "E"
	KeyF            KeyName = "F"
	KeyG            KeyName = "G"
	KeyH            KeyName = "H"
	KeyI            KeyName = "I"
	KeyJ            KeyName = "J"
	KeyK            KeyName = "K"
	KeyL            KeyName = "L"
	KeyM            KeyName = "M"
	KeyN            KeyName = "N"
	KeyO            KeyName = "O"
	KeyP            KeyName = "P"
	KeyQ            KeyName = "Q"
	KeyR            KeyName = "R"
	KeyS            KeyName = "S"
	KeyT            KeyName = "T"
	KeyU            KeyName = "U"
	KeyV            KeyName = "V"
	KeyW            KeyName = "W"
	KeyX            KeyName = "X"
	KeyY            KeyName = "Y"
	KeyZ            KeyName = "Z"
	KeySpace        KeyName = "Space"
	KeyApostrophe   KeyName = "'"
	KeyComma        KeyName = ","
	KeyMinus        KeyName = "-"
	KeyPeriod       KeyName = "."
	KeySlash        KeyName = "/"
	KeyBackslash    KeyName = "\\"
	KeyLeftBracket  KeyName = "["
	KeyRightBracket KeyName = "]"
	KeySemicolon    KeyName = ";"
	KeyEqual        KeyName = "="
	KeyAsterisk     KeyName = "*"
	KeyPlus         KeyName = "+"
	KeyBackTick     KeyName = "`"
	KeyUnknown      KeyName = ""
)

type LongPressable 

type LongPressable interface {
	LongPressed(*PointEvent)
}

LongPressable describes a CanvasObject that responds to long-press gestures. It is triggered when the user holds a pointer down without moving it for a duration (typically 300ms): a held finger on touch devices, and a held primary mouse button on desktop (#266), where the gesture fires while the button is still down and its release delivers no Tapped.

Unlike SecondaryTappable (which is triggered by right-click on desktop), LongPressable is the press-and-hold gesture. A widget can implement both interfaces to handle right-click and long-press differently.

A widget that may decline the gesture must answer the press some other way rather than ignore it: the drivers have already withheld the Tapped that would have followed.

type PointEvent 

type PointEvent struct {
	AbsolutePosition geo.Position // The absolute position of the event
	Position         geo.Position // The relative position of the event
}

PointEvent describes a pointer input event. The position is relative to the top-left of the CanvasObject this is triggered on.

type PreeditEvent 

type PreeditEvent struct {
	// Text is the composition (preedit) text to display inline. An empty
	// string clears any visible preedit without committing.
	Text string
	// CursorPos is the caret position within Text, measured in runes.
	CursorPos int
}

PreeditEvent describes in-progress IME composition (marked/preedit) text. During composition an input method shows tentative text inline before it is committed; the final committed text arrives separately via Composable.ComposeCommit.

Since: 1.0

type PreeditPositioner 

type PreeditPositioner interface {
	// PreeditCursorRectangle returns the caret rectangle in the object's content
	// coordinate space. A zero rectangle means the position is unknown.
	PreeditCursorRectangle() geo.Rectangle
}

PreeditPositioner is an optional capability of a Composable that reports the caret rectangle, in its own content coordinates, so a driver can position the IME candidate window near the text cursor.

Since: 1.0

type ScrollEvent 

type ScrollEvent struct {
	PointEvent
	Scrolled geo.Delta
	Source   ScrollSource
}

ScrollEvent defines the parameters of a pointer or other scroll event.

type ScrollSource 

type ScrollSource int

ScrollSource identifies the input device that generated a scroll event. 

const (
	// ScrollSourceUnknown indicates the scroll source is not known.
	ScrollSourceUnknown ScrollSource = iota

	// ScrollSourceMouseWheel indicates scrolling from a mouse scroll wheel.
	ScrollSourceMouseWheel

	// ScrollSourceTouchpad indicates scrolling from a touchpad gesture.
	ScrollSourceTouchpad

	// ScrollSourceTouch indicates scrolling from a direct touch gesture — a
	// finger dragging the content itself. Unlike the pointer sources it is
	// direct manipulation, so the delta is direction-absolute: a scroller
	// applies it raw, without the pointer conventions (right-to-left flip,
	// vertical-to-horizontal axis redirect) that a wheel or touchpad delta
	// goes through. Synthesized scrolls that mean "advance a page" rather
	// than "the content follows this finger" want a pointer source instead.
	ScrollSourceTouch
)

type Scrollable 

type Scrollable interface {
	Scrolled(*ScrollEvent)
}

Scrollable describes any CanvasObject that can be scrolled.

type SecondaryTappable 

type SecondaryTappable interface {
	TappedSecondary(*PointEvent)
}

SecondaryTappable describes a CanvasObject that can be right-clicked or long-tapped.

type Tabbable 

type Tabbable interface {
	AcceptsTab() bool
}

Tabbable describes any object that needs to accept Tab key presses.

type Tappable 

type Tappable interface {
	Tapped(*PointEvent)
}

Tappable describes any CanvasObject that can be tapped.

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.