keyboards

Documentation

Overview

StreamForce 2D

Copyright (c) 2026 AxleByte Studios.

Created by Ilzr Kr.

Licensed under the BSD 3-Clause License. See LICENSE for details.

StreamForce 2D

Copyright (c) 2026 AxleByte Studios.

Created by Ilzr Kr.

Licensed under the BSD 3-Clause License. See LICENSE for details.

StreamForce 2D

Copyright (c) 2026 AxleByte Studios.

Created by Ilzr Kr.

Licensed under the BSD 3-Clause License. See LICENSE for details.

StreamForce 2D

Copyright (c) 2026 AxleByte Studios.

Created by Ilzr Kr.

Licensed under the BSD 3-Clause License. See LICENSE for details.

Index

• Variables
• func ContainsAction[E types.Enum](acts []E, target E) bool
• func FormatKeycode(keycode sdl.Keycode) string
• func Quit[E types.Enum](engine *Engine[E])
• type Engine
  • func Init[E types.Enum](cps uint16) (*Engine[E], error)
  • func (e *Engine[E]) BindKey(key sdl.Keycode, target E)
  • func (e *Engine[E]) Destroy()
  • func (e *Engine[E]) DestroyBindings()
  • func (e *Engine[E]) Get(dst *[]E) (uint8, error)
  • func (e *Engine[E]) Handler() HandlerFunc[E]
  • func (e *Engine[E]) Lock()
  • func (e *Engine[E]) MustUpdate(event sdl.KeyboardEvent) bool
  • func (e *Engine[E]) ResetBindings()
  • func (e *Engine[E]) SetHandler(fn HandlerFunc[E])
  • func (e *Engine[E]) UnbindKey(key sdl.Keycode)
  • func (e *Engine[E]) Unlock()
• type HandlerFunc

Variables

var (
	// ErrAlreadyRunning occurs when the subsystem is already running.
	//
	// Format:
	//   "subsystem is already running"
	ErrAlreadyRunning error = errors.New("subsystem is already running")

	// ErrNotRunning occurs when the subsystem is not running.
	//
	// Format:
	//   "subsystem is not running"
	ErrNotRunning error = errors.New("subsystem is not running")
)

Functions

func ContainsAction

func ContainsAction[E types.Enum](acts []E, target E) bool

ContainsAction reports whether the given action is in the list of actions.

The actions must be sorted in alphabetical order for this function to work correctly.

Parameters:

• acts: The list of actions to search in.
• target: The action to search for.

Returns:

• bool: `true` if the action is in the list, `false` otherwise.

func FormatKeycode

func FormatKeycode(keycode sdl.Keycode) string

FormatKeycode returns a string representation of the given keycode.

Parameters:

• keycode: The keycode to format.

Returns:

• string: A string representation of the keycode.

func Quit

func Quit[E types.Enum](engine *Engine[E])

Quit destroys the keyboard sub system.

Parameters:

• engine: The keyboard sub system.

Types

type Engine

type Engine[E types.Enum] struct {
	// contains filtered or unexported fields
}

Engine is the main component of the keyboard sub system that manages keybinds in a thread-safe manner.

func Init

func Init[E types.Enum](cps uint16) (*Engine[E], error)

Init initializes the keyboard sub system with the given number of clicks per second.

CPS are limited between 1 and 1000.

Parameters:

• cps: The number of clicks per second.

Returns:

• *Engine[E]: The keyboard sub system.
• error: An error if starting the sub system fails.

Errors:

• ErrAlreadyRunning: If the sub system is already running.

func (*Engine[E]) BindKey

func (e *Engine[E]) BindKey(key sdl.Keycode, target E)

BindKey binds a key to an action. If the receiver is `nil`, this call is a no-op.

If the action is the zero value, the key is deleted from the virtual keyboard layout. Finally, if the key already has an action, then it is replaced. The action (0) is reserved for no action and so, not able to be bound.

This must be called between a [Lock] and an [Unlock].

Parameters:

• key: The key to bind.
• action: The action to bind.

func (*Engine[E]) Destroy

func (e *Engine[E]) Destroy()

Destroy destroys the engine.

func (*Engine[E]) DestroyBindings

func (e *Engine[E]) DestroyBindings()

DestroyBindings destroys all the key bindings. If the receiver is `nil`, this call is a no-op.

func (*Engine[E]) Get

func (e *Engine[E]) Get(dst *[]E) (uint8, error)

Get returns the actions that are currently being pressed.

The result is stored back into the provided memory location. While getting the actions, the presseds slice is reset.

Parameters:

• dst: The destination slice to store the actions in.

Returns:

• uint8: The number of actions in the list.
• error: An error if getting the actions fails.

Errors:

• errors.ErrNilReceiver: If the receiver is `nil`.
• errors.ErrBadParam: If the destination slice is `nil`.

func (*Engine[E]) Handler

func (e *Engine[E]) Handler() HandlerFunc[E]

Handler returns the handler function. If the receiver is `nil`, no handler function is returned.

Returns:

• HandlerFunc[E]: The handler function.

func (*Engine[E]) Lock

func (e *Engine[E]) Lock()

Lock locks the keyboard sub system for mass updating. If the receiver is `nil`, this is a no-op.

Once the operations are done, it is important to call [Unlock] after to avoid deadlocks.

func (*Engine[E]) MustUpdate

func (e *Engine[E]) MustUpdate(event sdl.KeyboardEvent) bool

MustUpdate implements [asl.MustUpdater].

func (*Engine[E]) ResetBindings

func (e *Engine[E]) ResetBindings()

ResetBindings resets the global bindings and make all the keys to unpressed. If the receiver is `nil`, this call is a no-op.

func (*Engine[E]) SetHandler

func (e *Engine[E]) SetHandler(fn HandlerFunc[E])

SetHandler sets the function that is called on each keyboard action. If the receiver is `nil`, this is a no-op.

If no function is set, this call removes the handler function.

Parameters:

• fn: The function that is called on each keyboard action.

func (*Engine[E]) UnbindKey

func (e *Engine[E]) UnbindKey(key sdl.Keycode)

UnbindKey unbinds a key from an action. If the receiver is `nil`, this is a no-op.

This must be called between a [Lock] and an [Unlock].

Parameters:

• key: The key to unbind.

func (*Engine[E]) Unlock

func (e *Engine[E]) Unlock()

Unlock unlocks the keyboard sub system. If the receiver is `nil`, this is a no-op.

This should only be used after calling [Lock].

type HandlerFunc

type HandlerFunc[E types.Enum] func(acts []E, n uint8)

HandlerFunc is the type for functions for handling keyboard actions.

Parameters:

• acts: The actions that are pressed.
• n: The number of actions in the list.