TermUI.Shortcut (TermUI v0.2.0)

View Source

Keyboard shortcut registry and matching.

Provides a system for registering keyboard shortcuts with actions, matching key events against registered shortcuts, and executing the associated actions.

Usage

# Create a registry
{:ok, registry} = Shortcut.start_link()

# Register shortcuts
Shortcut.register(registry, %Shortcut{
  key: :q,
  modifiers: [:ctrl],
  action: {:message, :root, :quit},
  scope: :global,
  description: "Quit application"
})

# Match key event
case Shortcut.match(registry, key_event, context) do
  {:ok, shortcut} -> Shortcut.execute(shortcut)
  :no_match -> :ignore
end

Summary

Types

action()
scope()
t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_sequence(registry)

Clears the partial sequence state.

execute(shortcut)

Executes a shortcut's action.

format(shortcut)

Formats a shortcut for display.

list(registry)

Lists all registered shortcuts.

list_for_scope(registry, scope)

Lists shortcuts for a specific scope.

match(registry, event, context \\ %{})

Matches a key event against registered shortcuts.

register(registry, shortcut)

Registers a shortcut.

start_link(opts \\ [])

Starts the shortcut registry.

unregister(registry, key, modifiers \\ [])

Unregisters a shortcut by key and modifiers.

Types

action()

@type action() ::
  {:function, (-> any())} | {:message, atom(), term()} | {:command, term()}

scope()

@type scope() :: :global | {:mode, atom()} | {:component, atom()}

t()

@type t() :: %TermUI.Shortcut{
  action: action(),
  description: String.t() | nil,
  key: atom() | String.t(),
  modifiers: [atom()],
  priority: integer(),
  scope: scope(),
  sequence: [atom() | String.t()] | nil
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_sequence(registry)

@spec clear_sequence(GenServer.server()) :: :ok

Clears the partial sequence state.

execute(shortcut)

@spec execute(t()) :: term()

Executes a shortcut's action.

Returns the result of the action execution.

format(shortcut)

@spec format(t()) :: String.t()

Formats a shortcut for display.

Examples

iex> Shortcut.format(%Shortcut{key: :s, modifiers: [:ctrl]})
"Ctrl+S"

iex> Shortcut.format(%Shortcut{key: :q, modifiers: [:ctrl, :shift]})
"Ctrl+Shift+Q"

list(registry)

@spec list(GenServer.server()) :: [t()]

Lists all registered shortcuts.

list_for_scope(registry, scope)

@spec list_for_scope(GenServer.server(), scope()) :: [t()]

Lists shortcuts for a specific scope.

match(registry, event, context \\ %{})

@spec match(GenServer.server(), TermUI.Event.Key.t(), map()) :: {:ok, t()} | :no_match

Matches a key event against registered shortcuts.

Returns {:ok, shortcut} if a match is found, or :no_match. The context determines which scopes are active.

register(registry, shortcut)

@spec register(GenServer.server(), t()) :: :ok

Registers a shortcut.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the shortcut registry.

unregister(registry, key, modifiers \\ [])

@spec unregister(GenServer.server(), atom() | String.t(), [atom()]) :: :ok

Unregisters a shortcut by key and modifiers.