app

package
v0.23.0 Latest Latest
Warning

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

 Go to latest Published: Nov 25, 2025 License: MIT Imports: 5 Imported by: 8

Documentation

Overview

Package app contains an API for working with an application window and the relevant input / output mechanisms that go with it.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// GamepadMinEventInterval is the minimum interval between
	// gamepad event processing. This is to ensure that even if there are no
	// native events, the gamepad will still produce events.
	GamepadMinEventInterval = 30 * time.Millisecond

	// GamepadRepeatDelay is the initial delay before a held down
	// gamepad button starts repeating.
	//
	// This value can be changed from the UI thread.
	GamepadRepeatDelay = 600 * time.Millisecond

	// GamepadRepeatInterval is the interval between repeated
	// gamepad button events after the initial delay.
	//
	// This value can be changed from the UI thread.
	GamepadRepeatInterval = 100 * time.Millisecond
)

Functions

This section is empty.

Types

type ClipboardEvent added in v0.13.0 

type ClipboardEvent struct {

	// Text holds the text stored in the clipboard.
	Text string
}

ClipboardEvent holds information related to the clipboard content.

type Controller 

type Controller interface {

	// OnCreate is called when the window has been created and is
	// ready to be used.
	OnCreate(window Window)

	// OnResize is called when the window's content area has been
	// resized.
	OnResize(window Window, width, height int)

	// OnFramebufferResize is called when the window's framebuffer has
	// been resized.
	// Note that the framebuffer need not match the content size. This
	// is mostly the case on devices with a high DPI setting.
	OnFramebufferResize(window Window, width, height int)

	// OnKeyboardEvent is called whenever a keyboard event has occurred.
	//
	// Return true to indicate that the event has been consumed and should
	// not be propagated to other potential receivers, otherwise return false.
	OnKeyboardEvent(window Window, event KeyboardEvent) bool

	// OnMouseEvent is called whenever a mouse event has occurred.
	//
	// Return true to indicate that the event has been consumed and should
	// not be propagated to other potential receivers, otherwise return false.
	OnMouseEvent(window Window, event MouseEvent) bool

	// OnGamepadEvent is called whenever a gamepad event has occurred.
	//
	// Return true to indicate that the event has been consumed and should
	// not be propagated to other potential receivers, otherwise return false.
	OnGamepadEvent(window Window, event GamepadEvent) bool

	// OnClipboardEvent is called whenever the clipboard content has been
	// requested and the underlying window has managed to retrieve it.
	OnClipboardEvent(window Window, event ClipboardEvent) bool

	// OnRender is called whenever the window would like to be redrawn.
	OnRender(window Window)

	// OnCloseRequested is called whenever the end-user has requested
	// that the application be closed through the native OS means
	// (e.g. pressing the close button or ALT+F4).
	//
	// Unlike regular events, returning false from this function indicates
	// that the operation should not be performed. Furthermore, the event will
	// not be passed to other potential receivers.
	//
	// Note that on some platforms (e.g. browser) returning false may invoke
	// a native warning dialog.
	OnCloseRequested(window Window) bool

	// OnDestroy is called before the window is closed.
	OnDestroy(window Window)
}

Controller is a mechanism through which the user code can be notified of changes to the application window.

All methods will be invoked on the UI thread (UI goroutine), unless otherwise specified.

type Cursor 

type Cursor interface {

	// Destroy releases all resources allocated for this cursor.
	Destroy()
}

Cursor represents the visual aspect of a pointer on the screen.

type CursorDefinition 

type CursorDefinition struct {

	// Path specifies the location of the image resource.
	Path string

	// HotspotX specifies the X click position within the cursor image.
	HotspotX int

	// HotspotY specifies the Y click position within the cursor image.
	HotspotY int
}

CursorDefinition can be used to describe a new cursor.

type Environment added in v0.13.0 

type Environment string

Environment represents the environment in which the app runs. 

const (
	// EnvironmentNative indicates a native app binary.
	EnvironmentNative Environment = "NATIVE"

	// EnvironmentBrowser indicates a browser page.
	EnvironmentBrowser Environment = "BROWSER"
)

type FilepathPayload added in v0.3.0 

type FilepathPayload struct {

	// Paths contains file paths to the dropped resources.
	Paths []string
}

FilepathPayload is a type of Payload that occurs when files have been dragged and dropped onto the window.

type Gamepad added in v0.10.0 

type Gamepad interface {

	// Connected returns whether this Gamepad is still connected. This is
	// useful for when a Gamepad instance is kept by the user code.
	Connected() bool

	// Supported returns whether the connected device can be mapped to the
	// standard layout:
	// https://w3c.github.io/gamepad/#remapping
	//
	// Devices that are not supported will return zero values for buttons
	// and axes.
	Supported() bool

	// StickDeadzone returns the range around 0.0 that will not be considered
	// valid for stick motion.
	StickDeadzone() float64

	// SetStickDeadzone changes the deadzone range for sticks.
	SetStickDeadzone(deadzone float64)

	// TriggerDeadzone returns the range around 0.0 that will not be considered
	// valid for trigger motion.
	TriggerDeadzone() float64

	// SetTriggerDeadzone changes the deadzone range for triggers.
	SetTriggerDeadzone(deadzone float64)

	// LeftStickX returns the horizontal axis of the left stick.
	LeftStickX() float64

	// LeftStickY returns the vertical axis of the left stick.
	LeftStickY() float64

	// LeftStickButton returns the button represented by pressing
	// on the left stick.
	LeftStickButton() bool

	// RightStickX returns the horizontal axis of the right stick.
	RightStickX() float64

	// RightStickY returns the horizontal axis of the right stick.
	RightStickY() float64

	// RightStickButton returns the button represented by pressing
	// on the right stick.
	RightStickButton() bool

	// LeftTrigger returns the left trigger button.
	LeftTrigger() float64

	// RightTrigger returns the right trigger button.
	RightTrigger() float64

	// LeftBumper returns the left bumper button.
	LeftBumper() bool

	// RightBumper returns the right bumper button.
	RightBumper() bool

	// DpadUpButton returns the up button of the left cluster.
	DpadUpButton() bool

	// DpadDownButton returns the down button of the left cluster.
	DpadDownButton() bool

	// DpadLeftButton returns the left button of the left cluster.
	DpadLeftButton() bool

	// DpadRightButton returns the right button of the left cluster.
	DpadRightButton() bool

	// ActionTopButton returns the up button of the right cluster.
	ActionUpButton() bool

	// ActionDownButton returns the down button of the right cluster.
	ActionDownButton() bool

	// ActionLeftButton returns the left button of the right cluster.
	ActionLeftButton() bool

	// ActionRightButton returns the right button of the right cluster.
	ActionRightButton() bool

	// ForwardButton represents the right button of the center cluster.
	ForwardButton() bool

	// BackButton represents the left button of the center cluster.
	BackButton() bool

	// Pulse causes the Gamepad controller to vibrate with the specified
	// intensity (0.0 to 1.0) for the specified duration.
	//
	// If the device does not have haptic feedback or if this API implementation
	// does not support it then this method does nothing.
	Pulse(intensity float64, duration time.Duration)
}

Gamepad represents a gamepad type joystick. Only input devides that can be mapped according to standard layout will work and have any axis and button output.

type GamepadAction added in v0.23.0 

type GamepadAction int

GamepadAction is used to specify the type of gamepad action that occurred. 

const (
	// GamepadActionNone indicates that no action occurred. This is an unlikely
	// value but allows for more custom event situations.
	GamepadActionNone GamepadAction = iota

	// GamepadActionConnected indicates that the gamepad was connected.
	GamepadActionConnected

	// GamepadActionDisconnected indicates that the gamepad was disconnected.
	GamepadActionDisconnected

	// GamepadActionButtonDown indicates that a gamepad button was pressed down.
	GamepadActionButtonDown

	// GamepadActionButtonUp indicates that a gamepad button was released.
	GamepadActionButtonUp

	// GamepadActionButtonRepeat indicates that a gamepad button is being held
	// down and is repeating.
	GamepadActionButtonRepeat

	// GamepadActionStickMove indicates that a gamepad stick or trigger was moved.
	GamepadActionStickMove
)

func (GamepadAction) String added in v0.23.0 

func (s GamepadAction) String() string

String returns a string representation of this event type,

type GamepadButton added in v0.23.0 

type GamepadButton int

GamepadButton represents the gamepad button. 

const (
	// GamepadButtonNone indicates that no button is associated with the event.
	GamepadButtonNone GamepadButton = iota

	// GamepadButtonLeftStick indicates the button represented by pressing
	// on the left stick.
	GamepadButtonLeftStick

	// GamepadButtonRightStick indicates the button represented by pressing
	// on the right stick.
	GamepadButtonRightStick

	// GamepadButtonLeftTrigger indicates the left trigger viewed as a button.
	GamepadButtonLeftTrigger

	// GamepadButtonRightTrigger indicates the right trigger viewed as a button.
	GamepadButtonRightTrigger

	// GamepadButtonLeftBumper indicates the left bumper button.
	GamepadButtonLeftBumper

	// GamepadButtonRightBumper indicates the right bumper button.
	GamepadButtonRightBumper

	// GamepadButtonDpadUp indicates the up button of the left cluster.
	GamepadButtonDpadUp

	// GamepadButtonDpadDown indicates the down button of the left cluster.
	GamepadButtonDpadDown

	// GamepadButtonDpadLeft indicates the left button of the left cluster.
	GamepadButtonDpadLeft

	// GamepadButtonDpadRight indicates the right button of the left cluster.
	GamepadButtonDpadRight

	// GamepadButtonActionUp indicates the up button of the right cluster.
	GamepadButtonActionUp

	// GamepadButtonActionDown indicates the down button of the right cluster.
	GamepadButtonActionDown

	// GamepadButtonActionLeft indicates the left button of the right cluster.
	GamepadButtonActionLeft

	// GamepadButtonActionRight indicates the right button of the right cluster.
	GamepadButtonActionRight

	// GamepadButtonForward indicates the right button of the center cluster.
	GamepadButtonForward

	// GamepadButtonBack indicates the left button of the center cluster.
	GamepadButtonBack

	// GamepadButtonLeftStickUp indicates the up direction on the left stick.
	GamepadButtonLeftStickUp

	// GamepadButtonLeftStickDown indicates the down direction on the left stick.
	GamepadButtonLeftStickDown

	// GamepadButtonLeftStickLeft indicates the left direction on the left stick.
	GamepadButtonLeftStickLeft

	// GamepadButtonLeftStickRight indicates the right direction on the left stick.
	GamepadButtonLeftStickRight

	// GamepadButtonRightStickUp indicates the up direction on the right stick.
	GamepadButtonRightStickUp

	// GamepadButtonRightStickDown indicates the down direction on the right stick.
	GamepadButtonRightStickDown

	// GamepadButtonRightStickLeft indicates the left direction on the right stick.
	GamepadButtonRightStickLeft

	// GamepadButtonRightStickRight indicates the right direction on the right stick.
	GamepadButtonRightStickRight

	// GamepadButtonCount is the total number of gamepad buttons enums.
	GamepadButtonCount
)

func (GamepadButton) String added in v0.23.0 

func (b GamepadButton) String() string

type GamepadEvent added in v0.23.0 

type GamepadEvent struct {

	// Index indicates which gamepad triggered the event. By default
	// the index for a the primary gamepad is 0.
	Index int

	// Gamepad is a reference to the gamepad that triggered the event.
	Gamepad Gamepad

	// Action indicates the action performed with the gamepad.
	Action GamepadAction

	// Button specifies the button for which the event is applicable.
	Button GamepadButton

	// Stick specifies the stick for which the event is applicable.
	Stick GamepadStick

	// X specifies the horizontal position of the stick.
	X float64

	// Y specifies the vertical position of the stick.
	Y float64
}

GamepadEvent represents an event related to a gamepad action.

func (GamepadEvent) String added in v0.23.0 

func (s GamepadEvent) String() string

String returns a string representation of this event.

type GamepadStick added in v0.23.0 

type GamepadStick int

GamepadStick is used to specify a particular stick on the gamepad. 

const (
	// GamepadStickNone indicates that no axis is associated with the event.
	GamepadStickNone GamepadStick = iota

	// GamepadStickLeft indicates the left stick.
	GamepadStickLeft

	// GamepadStickRight indicates the right stick.
	GamepadStickRight

	// GamepadStickLeftTrigger indicates the left trigger. Only the Y value
	// is applicable.
	GamepadStickLeftTrigger

	// GamepadStickRightTrigger indicates the right trigger. Only the Y value
	// is applicable.
	GamepadStickRightTrigger

	// GamepadStickCount is the total number of gamepad stick enums.
	GamepadStickCount
)

func (GamepadStick) String added in v0.23.0 

func (s GamepadStick) String() string

String returns a string representation of this stick.

type KeyCode 

type KeyCode int

KeyCode represents a keyboard key. 

const (
	KeyCodeEscape KeyCode = 1 + iota
	KeyCodeEnter
	KeyCodeSpace
	KeyCodeTab
	KeyCodeCaps
	KeyCodeLeftShift
	KeyCodeRightShift
	KeyCodeLeftControl
	KeyCodeRightControl
	KeyCodeLeftAlt
	KeyCodeRightAlt
	KeyCodeLeftSuper
	KeyCodeRightSuper
	KeyCodeBackspace
	KeyCodeInsert
	KeyCodeDelete
	KeyCodeHome
	KeyCodeEnd
	KeyCodePageUp
	KeyCodePageDown
	KeyCodeArrowLeft
	KeyCodeArrowRight
	KeyCodeArrowUp
	KeyCodeArrowDown
	KeyCodeMinus
	KeyCodeEqual
	KeyCodeLeftBracket
	KeyCodeRightBracket
	KeyCodeSemicolon
	KeyCodeComma
	KeyCodePeriod
	KeyCodeSlash
	KeyCodeBackslash
	KeyCodeApostrophe
	KeyCodeGraveAccent
	KeyCodeA
	KeyCodeB
	KeyCodeC
	KeyCodeD
	KeyCodeE
	KeyCodeF
	KeyCodeG
	KeyCodeH
	KeyCodeI
	KeyCodeJ
	KeyCodeK
	KeyCodeL
	KeyCodeM
	KeyCodeN
	KeyCodeO
	KeyCodeP
	KeyCodeQ
	KeyCodeR
	KeyCodeS
	KeyCodeT
	KeyCodeU
	KeyCodeV
	KeyCodeW
	KeyCodeX
	KeyCodeY
	KeyCodeZ
	KeyCode0
	KeyCode1
	KeyCode2
	KeyCode3
	KeyCode4
	KeyCode5
	KeyCode6
	KeyCode7
	KeyCode8
	KeyCode9
	KeyCodeF1
	KeyCodeF2
	KeyCodeF3
	KeyCodeF4
	KeyCodeF5
	KeyCodeF6
	KeyCodeF7
	KeyCodeF8
	KeyCodeF9
	KeyCodeF10
	KeyCodeF11
	KeyCodeF12
)

func (KeyCode) String added in v0.12.0 

func (c KeyCode) String() string

String returns a string representation of this key code.

type KeyboardAction added in v0.13.0 

type KeyboardAction int

KeyboardAction is used to specify the type of keyboard action that occurred. 

const (
	// KeyboardActionDown indicates that a keyboard key was pressed.
	KeyboardActionDown KeyboardAction = 1 + iota

	// KeyboardActionUp indicates that a keyboard key was released.
	KeyboardActionUp

	// KeyboardActionRepeat indicates that a keyboard key is being held pressed.
	KeyboardActionRepeat

	// KeyboardActionType indicates that a character is typed with the keyboard.
	//
	// Such actions would be duplicates of KeyboardActionDown and
	// KeyboardActionRepeat but allow for the character rune to be read which
	// might be the result of modifiers or special keys that would be hard
	// to reconstruct from just the key code.
	KeyboardActionType
)

func (KeyboardAction) String added in v0.13.0 

func (a KeyboardAction) String() string

String returns a string representation of this event type,

type KeyboardEvent 

type KeyboardEvent struct {

	// Action specifies the keyboard event type.
	Action KeyboardAction

	// Code returns the code of the keyboard key.
	Code KeyCode

	// Character returns the character that was typed in case
	// of an KeyboardActionType event.
	Character rune
}

KeyboardEvent is used to propagate events related to keyboard actions.

func (KeyboardEvent) String added in v0.13.0 

func (e KeyboardEvent) String() string

String returns a string representation of this event.

type LayeredController 

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

LayeredController is an implementation of Controller that invokes the specified controller layers in an order emulating multiple overlays of a window.

func NewLayeredController 

func NewLayeredController(layers ...Controller) *LayeredController

NewLayeredController returns a new LayeredController that has the specified controller layers configured.

func (*LayeredController) OnClipboardEvent added in v0.13.0 

func (c *LayeredController) OnClipboardEvent(window Window, event ClipboardEvent) bool

func (*LayeredController) OnCloseRequested 

func (c *LayeredController) OnCloseRequested(window Window) bool

func (*LayeredController) OnCreate 

func (c *LayeredController) OnCreate(window Window)

func (*LayeredController) OnDestroy 

func (c *LayeredController) OnDestroy(window Window)

func (*LayeredController) OnFramebufferResize 

func (c *LayeredController) OnFramebufferResize(window Window, width, height int)

func (*LayeredController) OnGamepadEvent added in v0.23.0 

func (c *LayeredController) OnGamepadEvent(window Window, event GamepadEvent) bool

func (*LayeredController) OnKeyboardEvent 

func (c *LayeredController) OnKeyboardEvent(window Window, event KeyboardEvent) bool

func (*LayeredController) OnMouseEvent 

func (c *LayeredController) OnMouseEvent(window Window, event MouseEvent) bool

func (*LayeredController) OnRender 

func (c *LayeredController) OnRender(window Window)

func (*LayeredController) OnResize 

func (c *LayeredController) OnResize(window Window, width, height int)

type MouseAction added in v0.13.0 

type MouseAction int

MouseAction represents the type of action performed with the mouse. 

const (
	// MouseActionDown indicates that a mouse button was pressed down.
	MouseActionDown MouseAction = 1 + iota

	// MouseActionUp indicates that a mouse button was released.
	MouseActionUp

	// MouseActionMove indicates that the mouse was moved.
	MouseActionMove

	// MouseActionEnter indicates that the mouse has entered the window.
	MouseActionEnter

	// MouseActionLeave indicates that the mouse has left the window.
	//
	// If the mouse was being dragged, further events may be sent from outside
	// the window boundary.
	MouseActionLeave

	// MouseActionDrop indicates that some payload was dropped onto the window.
	MouseActionDrop

	// MouseActionScroll indicates that the mouse wheel was scrolled.
	//
	// The ScrollX and ScrollY values of the event indicate the offset in
	// abstract units (comparable to pixels in magnitude).
	MouseActionScroll
)

func (MouseAction) String added in v0.13.0 

func (a MouseAction) String() string

String returns a string representation of this event type.

type MouseButton 

type MouseButton int

MouseButton represents the mouse button. 

const (
	// MouseButtonLeft specifies the left mouse button.
	MouseButtonLeft MouseButton = 1 + iota

	// MouseButtonMiddle specifies the middle mouse button.
	MouseButtonMiddle

	// MouseButtonRight specifies the right mouse button.
	MouseButtonRight
)

func (MouseButton) String 

func (b MouseButton) String() string

String returns a string representation of this button.

type MouseEvent 

type MouseEvent struct {

	// Index indicates which mouse triggered the event. By default
	// the index for a the primary mouse is 0.
	//
	// This is applicable for devices with multiple pointers
	// (mobile) or in case a second mouse is emulated
	// (e.g. with a game controller).
	Index int

	// Action indicates the action performed with the mouse.
	Action MouseAction

	// Button specifies the button for which the event is applicable.
	Button MouseButton

	// X specifies the horizontal position of the mouse.
	X int

	// Y specifies the vertical position of the mouse.
	Y int

	// ScrollX determines the amount of horizontal scroll.
	ScrollX float64

	// ScrollY determines the amount of vertical scroll.
	ScrollY float64

	// Payload contains any external data associated with the event.
	Payload any
}

MouseEvent represents an event related to a mouse action.

func (MouseEvent) String 

func (e MouseEvent) String() string

String returns a string representation of this event.

type NopController 

type NopController struct{}

NopController is a no-op implementation of a Controller.

func (NopController) OnClipboardEvent added in v0.13.0 

func (NopController) OnClipboardEvent(window Window, event ClipboardEvent) bool

func (NopController) OnCloseRequested 

func (NopController) OnCloseRequested(window Window) bool

func (NopController) OnCreate 

func (NopController) OnCreate(window Window)

func (NopController) OnDestroy 

func (NopController) OnDestroy(window Window)

func (NopController) OnFramebufferResize 

func (NopController) OnFramebufferResize(window Window, width, height int)

func (NopController) OnGamepadEvent added in v0.23.0 

func (NopController) OnGamepadEvent(window Window, event GamepadEvent) bool

func (NopController) OnKeyboardEvent 

func (NopController) OnKeyboardEvent(window Window, event KeyboardEvent) bool

func (NopController) OnMouseEvent 

func (NopController) OnMouseEvent(window Window, event MouseEvent) bool

func (NopController) OnRender 

func (NopController) OnRender(window Window)

func (NopController) OnResize 

func (NopController) OnResize(window Window, width, height int)

type OS added in v0.13.0 

type OS string

OS represents the operating system that runs the application regarless if native or via an intermediary like a browser. 

const (
	// OSLinux indicates the Linux operating system.
	OSLinux OS = "LINUX"

	// OSDarwin indicates the MacOS operating system.
	OSDarwin OS = "DARWIN"

	// OSWindows indicates the Windows operating system.
	OSWindows OS = "WINDOWS"

	// OSUnknown indicates that the operating system could not be determined.
	OSUnknown OS = "UNKNOWN"
)

type Platform added in v0.13.0 

type Platform interface {

	// Environment returns the current environment.
	Environment() Environment

	// OS returns the current operating system.
	OS() OS
}

Platform contains information on the system that is running the app.

type Window 

type Window interface {

	// Platform returns the information on the platform that is running the app.
	Platform() Platform

	// Title returns this window's title.
	Title() string

	// SetTitle changes the title of this window.
	SetTitle(title string)

	// Size returns the content area of this window.
	Size() (int, int)

	// SetSize changes the content area of this window.
	SetSize(width, height int)

	// FramebufferSize returns the texel size of the underlying framebuffer.
	// This would normally be used as reference when using graphics libraries
	// to draw on the screen as the framebuffer size may differ from the
	// window size.
	FramebufferSize() (int, int)

	// Gamepads returns an array of potentially available gamepad
	// controllers.
	//
	// Use the Connected and Supported methods on the Gamepad object to check
	// whether it is connected and can be used.
	//
	// This API supports up to 4 connected devices.
	Gamepads() [4]Gamepad

	// Schedule queues a function to be called on the main thread
	// when possible. There are no guarantees that it will necessarily
	// be on the next frame iteration.
	Schedule(fn func())

	// Invalidate causes this window to be redrawn when possible.
	Invalidate()

	// CreateCursor creates a new cursor object based on the specified
	// definition.
	CreateCursor(definition CursorDefinition) Cursor

	// UseCursor changes the currently displayed cursor on the screen.
	// Specifying nil returns the default cursor.
	UseCursor(cursor Cursor)

	// CursorVisible returns whether a cursor is to be displayed on the
	// screen. This is determined based on the visibility and lock settings
	// of the cursor
	CursorVisible() bool

	// SetCursorVisible changes whether a cursor is displayed on the
	// screen.
	SetCursorVisible(visible bool)

	// SetCursorLocked traps the cursor within the boundaries of the window
	// and reports relative motion events. This method also hides the cursor.
	SetCursorLocked(locked bool)

	// RequestCopy requests that the specified text be stored in the clipboard.
	RequestCopy(text string)

	// RequestPaste requests that the clipboard be read and the content be
	// passed down through an event.
	RequestPaste()

	// RenderAPI provides access to a usable Render API based on the current
	// window's screen.
	//
	// If the implementation of this API does not support graphics, then this
	// method returns nil.
	RenderAPI() render.API

	// AudioAPI provides access to a usable Audio API based on the current
	// window.
	//
	// If the implementation of this API does not support audio, then this
	// method returns nil.
	AudioAPI() audio.API

	// Close disposes of this window.
	Close()
}

Window represents a native application window.

All methods must be invoked on the UI thread (UI goroutine), unless otherwise specified.

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.