mouse

Documentation

Overview

Package mouse handles the propagation of mouse events though clickable regions. It extends the functionality of the collision package.

Index

• Constants
• Variables
• func Add(sps ...*collision.Space)
• func Clear()
• func EventOn(ev event.EventID[*Event]) (event.EventID[*Event], bool)
• func EventRelative(ev event.EventID[*Event]) (event.EventID[*Event], bool)
• func GetEvent(d mouse.Direction, b mouse.Button) event.EventID[*Event]
• func HitLabel(sp *collision.Space, labels ...collision.Label) *collision.Space
• func Hits(sp *collision.Space) []*collision.Space
• func PhaseCollision(s *collision.Space, handler event.Handler) error
• func Remove(sps ...*collision.Space)
• func ShiftSpace(x, y float64, s *collision.Space) error
• func UpdateSpace(x, y, w, h float64, s *collision.Space) error
• type Button
• type CollisionPhase
  • func (cp *CollisionPhase) CID() event.CallerID
• type Event
  • func NewEvent(x, y float64, button Button, ev event.EventID[*Event]) Event
  • func (e Event) ToSpace() *collision.Space

Constants

const (
	MinZLayer = 0
	MaxZLayer = 1000
)

Min and Max Z layer inform what range of z layer values will be checked on mouse collision interactions. Mouse events will not propagate to elements with z layers outside of this range.

const (
	ButtonLeft       = mouse.ButtonLeft
	ButtonMiddle     = mouse.ButtonMiddle
	ButtonRight      = mouse.ButtonRight
	ButtonWheelDown  = mouse.ButtonWheelDown
	ButtonWheelUp    = mouse.ButtonWheelUp
	ButtonWheelLeft  = mouse.ButtonWheelLeft
	ButtonWheelRight = mouse.ButtonWheelRight
	ButtonNone       = mouse.ButtonNone
)

Valid Button event types

Variables

var (
	// LastEvent is the last triggered mouse event,
	// tracked for continuous mouse responsiveness on events
	// that don't take in a mouse event
	LastEvent = Event{}
	// LastPress is the last triggered mouse event,
	// where the mouse event was a press.
	LastPress = Event{}
)

var (
	// Press is triggered when a mouse key is pressed down
	Press = event.RegisterEvent[*Event]()
	// Release is triggered when a mouse key, pressed, is released
	Release = event.RegisterEvent[*Event]()
	// ScrollDown is triggered when a mouse's scroll wheel scrolls downward
	ScrollDown = event.RegisterEvent[*Event]()
	// ScrollUp is triggered when a mouse's scroll wheel scrolls upward
	ScrollUp = event.RegisterEvent[*Event]()
	// Click is triggered when a Release follows a press for the same mouse key without
	// other mouse key presses intertwining.
	Click = event.RegisterEvent[*Event]()
	// Drag is triggered when the mouse is moved.
	Drag = event.RegisterEvent[*Event]()

	// The 'On' Variants of all mouse events are triggered when a mouse event occurs on
	// a specific entity in a mouse collision tree.
	PressOn      = event.RegisterEvent[*Event]()
	ReleaseOn    = event.RegisterEvent[*Event]()
	ScrollDownOn = event.RegisterEvent[*Event]()
	ScrollUpOn   = event.RegisterEvent[*Event]()
	ClickOn      = event.RegisterEvent[*Event]()
	DragOn       = event.RegisterEvent[*Event]()

	// Relative variants are like 'On' variants, but their mouse position data is relative to
	// the window's current viewport. E.g. if the viewport is at 100,100 and a click happens at
	// 100,100 on the window-- Relative will report 100,100, and non-relative will report 200,200.
	// TODO: re-evaluate relative vs non-relative mouse events
	RelativePressOn      = event.RegisterEvent[*Event]()
	RelativeReleaseOn    = event.RegisterEvent[*Event]()
	RelativeScrollDownOn = event.RegisterEvent[*Event]()
	RelativeScrollUpOn   = event.RegisterEvent[*Event]()
	RelativeClickOn      = event.RegisterEvent[*Event]()
	RelativeDragOn       = event.RegisterEvent[*Event]()
)

var (
	Start = event.RegisterEvent[*Event]()
	Stop  = event.RegisterEvent[*Event]()
)

MouseCollisionStart/Stop: see collision Start/Stop, for mouse collision

var (
	DefaultTree = collision.NewTree()
)

DefaultTree is a collision tree intended to be used by default if no other is instantiated. Methods on a collision tree are duplicated as functions in this package, so `tree.Add(...)` can instead be `mouse.Add(...)` if the codebase is coordinated to just use the default tree.

Functions

func Add

func Add(sps ...*collision.Space)

Add adds a set of spaces to the rtree

func Clear

func Clear()

Clear resets the default collision tree

func EventOn

func EventOn(ev event.EventID[*Event]) (event.EventID[*Event], bool)

EventOn converts a generic positioned mouse event into its variant indicating it occurred on a CallerID targetted entity

func EventRelative

func EventRelative(ev event.EventID[*Event]) (event.EventID[*Event], bool)

func GetEvent

func GetEvent(d mouse.Direction, b mouse.Button) event.EventID[*Event]

GetEventName returns a string event name given some mobile/mouse information

func HitLabel

func HitLabel(sp *collision.Space, labels ...collision.Label) *collision.Space

HitLabel acts like hits, but reutrns the first space within hits that matches one of the input labels

func Hits

func Hits(sp *collision.Space) []*collision.Space

Hits returns the set of spaces which are colliding with the passed in space.

func PhaseCollision

func PhaseCollision(s *collision.Space, handler event.Handler) error

PhaseCollision binds to the entity behind the space's CID so that it will receive MouseCollisionStart and MouseCollisionStop events, appropriately when the mouse begins to hover or stops hovering over the input space.

func Remove

func Remove(sps ...*collision.Space)

Remove removes a space from the rtree

func ShiftSpace

func ShiftSpace(x, y float64, s *collision.Space) error

ShiftSpace adds x and y to a space and updates its position in the collision rtree that should not be a package global

func UpdateSpace

func UpdateSpace(x, y, w, h float64, s *collision.Space) error

UpdateSpace resets a space's location to a given rtreego.Rect. This is not an operation on a space because a space can exist in multiple rtrees.

Types

type Button

type Button = mouse.Button

Button represents a mouse interaction type, like a left button or mouse wheel movement.

type CollisionPhase

type CollisionPhase struct {
	OnCollisionS *collision.Space
	CallerMap    *event.CallerMap
	LastEvent    *Event
	// contains filtered or unexported fields
}

CollisionPhase is a component that can be placed into another struct to enable PhaseCollision on the struct. See PhaseCollision.

func (*CollisionPhase) CID

func (cp *CollisionPhase) CID() event.CallerID

type Event

type Event struct {
	floatgeom.Point2
	Button
	EventType event.EventID[*Event]

	// Set StopPropagation on a mouse event to prevent it from triggering on
	// lower layers of mouse collision spaces while in flight
	StopPropagation bool
}

An Event is passed in through all Mouse related event bindings to indicate what type of mouse event was triggered, where it was triggered, and which mouse button it concerns.

func NewEvent

func NewEvent(x, y float64, button Button, ev event.EventID[*Event]) Event

NewEvent creates an event.

func (Event) ToSpace

func (e Event) ToSpace() *collision.Space

ToSpace converts a mouse event into a collision space