ExTermbox (ExTermbox v1.1.3)

View Source

Elixir bindings for the termbox library, providing a way to control the terminal and draw simple UIs.

This module provides the main user-facing API. It interacts with a C process via an Elixir Port managed by the ExTermbox.PortHandler GenServer.

Usage

  1. Initialization: Call ExTermbox.init/1 to start the necessary processes. This returns {:ok, pid} where pid is the handler process. This must be called before any other functions.
  2. API Calls: Use functions like change_cell/6, clear/1, etc., passing the pid obtained from init/1 as the first argument.
  3. Display: Call ExTermbox.present/1 (passing the pid) to flush the back buffer to the terminal screen.
  4. Events: Call ExTermbox.poll_event/1 (passing the pid) to wait for user input or resize events. These will be sent as messages to the process that called init/1 (the owner).
  5. Shutdown: Call ExTermbox.shutdown/1 (passing the pid) when finished to clean up.

Event Handling

Events are delivered as messages in the format {:termbox_event, event_map} to the process that called init/1. See ExTermbox.PortHandler for details on the event map structure. You typically need to call poll_event/1 again after receiving an event to wait for the next one.

Example (handle_info in the process that called init/1):

def handle_info({:termbox_event, event}, state) do
  # Assuming handler_pid is stored in state
  handler_pid = state.handler_pid
  IO.inspect(event, label: "Received Termbox Event")
  # Request next event, passing the pid
  ExTermbox.poll_event(handler_pid)
  {:noreply, state}
end

Summary

Functions

Changes the character, foreground, and background attributes of a specific cell.

Clears the terminal buffer using the default colors.

[Debug] Causes the C helper process to exit immediately. FOR TESTING ONLY.

Retrieves the content of a specific cell from the back buffer.

Returns the height of the terminal.

Initializes the termbox library.

Requests the PortHandler to poll for the next event. This is typically called after handling a previous event. The event will be delivered asynchronously to the owning process.

Synchronizes the back buffer with the terminal screen.

Prints a string at the specified position with given attributes.

Selects the input mode.

Sets the default foreground and background attributes used by clear/1.

Sets the cursor position. Use (-1, -1) to hide the cursor.

Selects the output mode.

Shuts down the termbox library and stops the PortHandler GenServer.

Returns the width of the terminal.

Types

pid_or_name()

@type pid_or_name() :: pid() | atom()

Functions

change_cell(pid_or_name, x, y, char, fg, bg)

Changes the character, foreground, and background attributes of a specific cell.

Requires the PID or registered name of the PortHandler process.

Arguments:

  • pid_or_name: The PID or registered name of the PortHandler.
  • x: The zero-based column index.
  • y: The zero-based row index.
  • char: The character (as a single-char string or integer codepoint).
  • fg: The foreground attribute (e.g., ExTermbox.Const.Color.RED).
  • bg: The background attribute (e.g., ExTermbox.Const.Attribute.BOLD).

clear(pid_or_name)

@spec clear(pid() | atom()) :: :ok | {:error, any()}

Clears the terminal buffer using the default colors.

Requires the PID or registered name of the PortHandler process.

debug_crash(pid_or_name)

@spec debug_crash(pid() | atom()) :: :ok | {:error, any()}

[Debug] Causes the C helper process to exit immediately. FOR TESTING ONLY.

Requires the PID or registered name of the PortHandler process.

debug_send_event(pid_or_name, type_atom, mod_atom, key_atom, ch \\ 0, w \\ 0, h \\ 0, x \\ 0, y \\ 0)

@spec debug_send_event(
  pid() | atom(),
  atom(),
  atom(),
  atom(),
  integer(),
  integer(),
  integer(),
  integer(),
  integer()
) :: :ok | {:error, any()}

[Debug] Sends a synthetic event for testing purposes.

Requires the PID or registered name of the PortHandler process.

get_cell(pid_or_name, x, y)

@spec get_cell(pid() | atom(), integer(), integer()) :: {:ok, map()} | {:error, any()}

Retrieves the content of a specific cell from the back buffer.

Requires the PID or registered name of the PortHandler process.

Arguments:

  • pid_or_name: The PID or registered name of the PortHandler.
  • x: The zero-based column index.
  • y: The zero-based row index.

Returns {:ok, cell_map} or {:error, reason}. The cell_map has keys :x, :y, :char, :fg, :bg.

height(pid_or_name)

@spec height(pid() | atom()) :: {:ok, non_neg_integer()} | {:error, any()}

Returns the height of the terminal.

Requires the PID or registered name of the PortHandler process.

init(opts \\ [])

@spec init(keyword()) :: {:ok, pid()} | {:error, any()}

Initializes the termbox library.

Starts the PortHandler GenServer. Returns {:ok, pid} on success, where pid is the PortHandler process ID, or {:error, reason} on failure.

Options:

  • name: Registers the GenServer under a specific name.
  • owner: Specifies the owner process (defaults to self()).

poll_event(pid_or_name)

@spec poll_event(pid() | atom()) :: :ok | {:error, any()}

Requests the PortHandler to poll for the next event. This is typically called after handling a previous event. The event will be delivered asynchronously to the owning process.

Requires the PID or registered name of the PortHandler process.

present(pid_or_name)

@spec present(pid() | atom()) :: :ok | {:error, any()}

Synchronizes the back buffer with the terminal screen.

Requires the PID or registered name of the PortHandler process.

print(pid_or_name, x, y, fg, bg, string)

@spec print(pid_or_name(), integer(), integer(), atom(), atom(), String.t()) ::
  :ok | {:error, any()}

Prints a string at the specified position with given attributes.

Requires the PID or registered name of the PortHandler process.

Arguments:

  • pid_or_name: The PID or registered name of the PortHandler.
  • x: The zero-based column index for the start of the string.
  • y: The zero-based row index for the start of the string.
  • fg: The foreground attribute (e.g., ExTermbox.Const.Color.RED).
  • bg: The background attribute (e.g., ExTermbox.Const.Attribute.BOLD).
  • string: The string to print.

select_input_mode(pid_or_name, mode)

@spec select_input_mode(pid_or_name(), atom()) :: :ok | {:error, any()}

Selects the input mode.

Requires the PID or registered name of the PortHandler process.

Arguments:

  • pid_or_name: The PID or registered name of the PortHandler.
  • mode: An atom representing the input mode (e.g., ExTermbox.Const.Input.ESC).

set_clear_attributes(pid_or_name, fg, bg)

@spec set_clear_attributes(pid_or_name(), atom(), atom()) :: :ok | {:error, any()}

Sets the default foreground and background attributes used by clear/1.

Requires the PID or registered name of the PortHandler process.

Arguments:

  • pid_or_name: The PID or registered name of the PortHandler.
  • fg: The foreground attribute.
  • bg: The background attribute.

set_cursor(pid_or_name, x, y)

@spec set_cursor(pid() | atom(), integer(), integer()) :: :ok | {:error, any()}

Sets the cursor position. Use (-1, -1) to hide the cursor.

Requires the PID or registered name of the PortHandler process.

Arguments:

  • pid_or_name: The PID or registered name of the PortHandler.
  • x: The zero-based column index, or -1 to hide.
  • y: The zero-based row index, or -1 to hide.

set_output_mode(pid_or_name, mode)

@spec set_output_mode(pid_or_name(), atom()) :: :ok | {:error, any()}

Selects the output mode.

Requires the PID or registered name of the PortHandler process.

Arguments:

  • pid_or_name: The PID or registered name of the PortHandler.
  • mode: An atom representing the output mode (e.g., ExTermbox.Const.OutputMode.C256).

shutdown(pid_or_name)

@spec shutdown(pid() | atom()) :: :ok | {:error, any()}

Shuts down the termbox library and stops the PortHandler GenServer.

Requires the PID or registered name of the PortHandler process.

start_link(opts \\ [])

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

width(pid_or_name)

@spec width(pid() | atom()) :: {:ok, non_neg_integer()} | {:error, any()}

Returns the width of the terminal.

Requires the PID or registered name of the PortHandler process.