ExTermbox v0.3.3 ExTermbox.Bindings View Source

Provides the low-level bindings to the termbox library. This module loads the NIFs defined in c_src/ and thinly wraps the C interface.

For event-handling, it's recommended to use the ExTermbox.EventManager API instead of the raw interface exposed here.

For more complex applications, it's recommended to use the high-level rendering API provided by Ratatouille (a terminal UI kit based on the bindings here). Ratatouille manages things like initialization, updates and shutdown automatically, and provides a declarative, HTML-like interface for rendering content to the screen. See the repo for details:

https://github.com/ndreynolds/ratatouille

See also the termbox header file for additional documentation of the functions here:

https://github.com/nsf/termbox/blob/master/src/termbox.h

Note that the "NIF / not loaded" messages below are fallbacks normally replaced by the natively-implemented functions at load. If you're seeing this message, it means the native bindings could not be loaded. Please open an issue with the error and relevant system information.

Link to this section Summary

Functions

Changes the attributes of the cell at the specified position in the internal back buffer. Prefer using put_cell/1, which supports passing an ExTermbox.Cell struct

Clears the internal back buffer, setting the foreground and background to the defaults, or those specified by set_clear_attributes/2

Returns the height of the terminal window in characters. Undefined before init/0 is called

Initializes the termbox library. Must be called before any other bindings are called

Not yet implemented. For most cases, poll_event/1 should be sufficient

Polls for a terminal event asynchronously. The function accepts a PID as argument and returns immediately. When an event is received, it's sent to the specified process. To receive additional events, it's necessary to call this function again

Synchronizes the internal back buffer and the terminal

Puts a cell in the internal back buffer at the cell's position. Note that this is implemented in terms of change_cell/5

Sets or retrieves the input mode (see ExTermbox.Constants.input_modes/0). See the termbox source for additional documentation

Sets or retrieves the output mode (see ExTermbox.Constants.output_modes/0). See the termbox source for additional documentation

Sets the default foreground and background colors used when clear/0 is called

Sets the position of the cursor to the coordinates (x, y), or hide the cursor by passing ExTermbox.Constants.hide_cursor/0 for both x and y

Finalizes the termbox library. Should be called when the terminal application is exited, and before your program or OTP application stops

Returns the width of the terminal window in characters. Undefined before init/0 is called

Link to this section Functions

Changes the attributes of the cell at the specified position in the internal back buffer. Prefer using put_cell/1, which supports passing an ExTermbox.Cell struct.

Clears the internal back buffer, setting the foreground and background to the defaults, or those specified by set_clear_attributes/2.

Returns the height of the terminal window in characters. Undefined before init/0 is called.

Link to this function

init() View Source
init() :: :ok | {:error, integer()}

Initializes the termbox library. Must be called before any other bindings are called.

Returns :ok on success. On error, returns a tuple {:error, code} containing an integer representing a termbox error code.

Link to this function

peek_event(pid, timeout) View Source

Not yet implemented. For most cases, poll_event/1 should be sufficient.

Link to this function

poll_event(pid) View Source
poll_event(pid()) :: reference()

Polls for a terminal event asynchronously. The function accepts a PID as argument and returns immediately. When an event is received, it's sent to the specified process. To receive additional events, it's necessary to call this function again.

In the underlying NIF, a thread is created which performs the blocking event poll. This allows the NIF to return quickly and avoid causing trouble for the scheduler.

Note that the ExTermbox.EventManager is an abstraction over this function that listens continuously for events and supports multiple subscriptions.

Returns a resource representing a handle for the poll thread.

Link to this function

present() View Source
present() :: :ok

Synchronizes the internal back buffer and the terminal.

Puts a cell in the internal back buffer at the cell's position. Note that this is implemented in terms of change_cell/5.

Link to this function

select_input_mode(mode) View Source
select_input_mode(ExTermbox.Constants.input_mode()) :: integer()

Sets or retrieves the input mode (see ExTermbox.Constants.input_modes/0). See the termbox source for additional documentation.

Returns an integer representing the input mode.

Link to this function

select_output_mode(mode) View Source
select_output_mode(ExTermbox.Constants.output_mode()) :: integer()

Sets or retrieves the output mode (see ExTermbox.Constants.output_modes/0). See the termbox source for additional documentation.

Returns an integer representing the output mode.

Link to this function

set_clear_attributes(fg, bg) View Source
set_clear_attributes(ExTermbox.Constants.color(), ExTermbox.Constants.color()) ::
  :ok

Sets the default foreground and background colors used when clear/0 is called.

Sets the position of the cursor to the coordinates (x, y), or hide the cursor by passing ExTermbox.Constants.hide_cursor/0 for both x and y.

Link to this function

shutdown() View Source
shutdown() :: :ok | {:error, integer()}

Finalizes the termbox library. Should be called when the terminal application is exited, and before your program or OTP application stops.

Returns the width of the terminal window in characters. Undefined before init/0 is called.