Getting Started

Getting Started

This page shows the minimum shape of a C termbox-glib program. If the termbox2 drawing model is new to you, read termbox concepts first.

Build Requirements

termbox-glib depends on GLib and GObject. Applications compile against the installed pkg-config package:

cc hello.c `pkg-config --cflags --libs termbox-glib-0.1` -o hello

Use the umbrella header:

#include <termbox-glib.h>

Hello Terminal

The simplest program creates a TbgTerminal, draws text into the back buffer, and presents the buffer:

#include <glib.h>
#include <termbox-glib.h>

int
main (void)
{
  g_autoptr (TbgTerminal) terminal = tbg_terminal_new (NULL);

  if (terminal == NULL)
    return 1;

  TbgAttr fg = tbg_attr_color (TBG_COLOR_GREEN, TBG_ATTR_FLAGS_BOLD);
  TbgAttr bg = tbg_attr_default ();

  tbg_terminal_print (terminal, 0, 0, fg, bg, "hello from termbox-glib", NULL);
  tbg_terminal_present (terminal, NULL);

  g_usleep (G_USEC_PER_SEC * 3);

  return 0;
}

The sleep keeps the message visible for three seconds. When terminal is finalized, termbox2 is shut down and the terminal mode is restored.

Only one terminal can be alive at a time. Create it once, pass the object to the code that needs it, or use tbg_terminal_get_default() to retrieve the current terminal.

TbgTerminal should be created, used, and destroyed on the main thread. termbox2 uses process-global terminal state and termbox-glib does not add locking around it. Attach event sources to the main-thread GMainContext and call terminal methods from that same thread.

Waiting for Events

To receive input without blocking GLib, attach the terminal event source to a GMainContext and listen to typed terminal signals:

#include <glib.h>
#include <termbox-glib.h>

static void
on_key (TbgTerminal *terminal, TbgKeyEvent *event, gpointer user_data)
{
  GMainLoop *loop = user_data;

  if (tbg_key_event_get_char (event) == 'q')
    g_main_loop_quit (loop);
}

int
main (void)
{
  g_autoptr (TbgTerminal) terminal = tbg_terminal_new (NULL);
  g_autoptr (GSource) source = NULL;
  g_autoptr (GMainLoop) loop = NULL;

  if (terminal == NULL)
    return 1;

  loop = g_main_loop_new (NULL, FALSE);
  g_signal_connect (terminal, "key", G_CALLBACK (on_key), loop);

  TbgAttr fg = tbg_attr_color (TBG_COLOR_GREEN, TBG_ATTR_FLAGS_BOLD);
  TbgAttr bg = tbg_attr_default ();
  tbg_terminal_print (terminal, 0, 0, fg, bg, "press q to quit", NULL);
  tbg_terminal_present (terminal, NULL);

  source = tbg_terminal_create_event_source (terminal, NULL);
  if (source == NULL)
    return 1;

  g_source_attach (source, NULL);
  g_main_loop_run (loop);
  g_source_destroy (source);

  return 0;
}

For complete examples, see the C, Vala, and GJS programs in the examples directory.

Next Steps