ExTermbox (ExTermbox v1.1.3)
View SourceElixir 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
- Initialization: Call
ExTermbox.init/1
to start the necessary processes. This returns{:ok, pid}
wherepid
is the handler process. This must be called before any other functions. - API Calls: Use functions like
change_cell/6
,clear/1
, etc., passing thepid
obtained frominit/1
as the first argument. - Display: Call
ExTermbox.present/1
(passing thepid
) to flush the back buffer to the terminal screen. - Events: Call
ExTermbox.poll_event/1
(passing thepid
) to wait for user input or resize events. These will be sent as messages to the process that calledinit/1
(the owner). - Shutdown: Call
ExTermbox.shutdown/1
(passing thepid
) 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.
[Debug] Sends a synthetic event for testing purposes.
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
Functions
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
).
Clears the terminal buffer using the default colors.
Requires the PID or registered name of the PortHandler process.
[Debug] Causes the C helper process to exit immediately. FOR TESTING ONLY.
Requires the PID or registered name of the PortHandler process.
@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.
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
.
@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.
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 toself()
).
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.
Synchronizes the back buffer with the terminal screen.
Requires the PID or registered name of the PortHandler process.
@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.
@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
).
@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.
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.
@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
).
Shuts down the termbox library and stops the PortHandler GenServer.
Requires the PID or registered name of the PortHandler process.
@spec start_link(keyword()) :: GenServer.on_start()
@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.