TICKIT(7)

💖 TICKIT(7) — Terminal Interface Construction KIT 💖

okay bestie, sit down, hydrate, and let me tell you about tickit — short for Terminal Interface Construction KIT. It lives in the Miscellaneous Information Manual section 7, and it's literally the whole vibe of building full-screen terminal apps. 🦋

---

✨ SYNOPSIS ✨

#include <tickit.h>

typedef struct Tickit;

---

🌸 DESCRIPTION 🌸

so here's the tea ☕ — tickit is a library for building full-screen interactive programs that use a terminal interface. A program using this library would start by creating a toplevel Tickit instance, and from that instance you spin up one or more divisions of the terminal area, called "windows". 🪟✨

These windows form a heirarchial tree that subdivides the content area into independent regions that can be managed by different parts of the program structure. And every single window can react to input events like keyboard or mouse interaction. main character energy for real. 💅

And like, as well as creating the initial root window, the toplevel Tickit instance also performs a few other jobs for the containing program. It can act as a containing event loop for the program, doing IO multiplexing tasks both for tickit's own needs and the needs of the program as a whole. it's giving multitasking queen 👑

---

🎀 FUNCTIONS 🎀

A new toplevel instance is created by using tickit_build(3), tickit_new_stdio(3) or tickit_new_stdtty(3). A toplevel instance stores a reference count to make it easier for applications to manage its lifetime. new instance = count of one, bestie, remember that — and it can be adjusted using tickit_ref(3) and tickit_unref(3). When the count reaches zero the instance is destroyed. 💀 (affectionately)

The toplevel instance manages a tree of TickitWindow instances. The root of this tree is obtained by tickit_get_rootwin(3), and after that it can be divided further by other functions on the window, described more in tickit_window(7). 🌳

The TickitTerm instance behind the toplevel instance can be obtained by tickit_get_term(3), and is described more in tickit_term(7).

Event handling callback functions can be installed to be called at a later time, by using tickit_watch_io(3), tickit_watch_timer_after_msec(3), tickit_watch_timer_after_tv(3), tickit_watch_later(3), tickit_watch_signal(3) or tickit_watch_process(3). The main IO event loop is controlled using tickit_run(3) and tickit_stop(3). set it up, run it, stop it — no cap 🫶

The compile-time and run-time version of the library can be inspected using the macros and functions described in tickit_version(7).

---

🌈 TYPICAL STRUCTURE 🌈

A typical program using this library would start by creating the toplevel instance, by calling tickit_new_stdtty(3), then obtain its root window on it by calling tickit_get_rootwin(3). step one, step two, we love a routine ✨

This root window can then be sub-divided into regions of interest by calling tickit_window_new(3) to build a tree of windows. Windows can then have some event handlers attached by calling tickit_window_bind_event(3) — each window will need to handle the TICKIT_WINDOW_ON_EXPOSE event, but might also wish to handle other kinds like geometry change for dynamic resizing, or keyboard or mouse to react to user input. 👀

Finally, once the initial window tree is created, the program would enter the main event loop by invoking tickit_run(3). and then you just vibe 🦋

---

💜 COMMON TYPES 💜

The flags argument to the various tickit_..._bind_event() functions should be zero, or a bitmask of the following constants.

typedef enum {
  TICKIT_BIND_FIRST,
  TICKIT_BIND_UNBIND,
  TICKIT_BIND_DESTROY,
  TICKIT_BIND_ONESHOT,
} TickitBindFlags;

• TICKIT_BIND_FIRST — says this handler should be inserted at the start of the list, rather than the default position at the end. cutting the line, iconic 💅
• TICKIT_BIND_UNBIND — says this handler should also be invoked at the time it is unbound, either due to a specific call to the tickit_..._unbind_event() function, or because the bound object is being destroyed.
• TICKIT_BIND_DESTROY — says this handler should also be invoked at the time that the bound object is being destroyed. 💀
• TICKIT_BIND_ONESHOT — says the handler should be invoked at-most once, and unbound the first time it is invoked. When invoked it will receive both the TICKIT_EV_FIRE and TICKIT_EV_UNBIND flags at once. one and done, periodt ✨

---

Some API functions take or return the following enum type, to represent a tri-state extended boolean concept of true, false, or some third condition typically indicating a "don't care" or "unknown" state; the exact semantics will vary between specific uses and should be documented specifically. ngl, TICKIT_MAYBE is such a mood 😭

typedef enum {
  TICKIT_YES = 1,
  TICKIT_NO = 0,
  TICKIT_MAYBE = -1,
} TickitMaybeBool;

---

The various tickit_*ctl_type() and tickit_pen_attrtype(3) functions return the following enum type, to indicate what type of value each individual control or attribute takes.

typedef enum {
  TICKIT_TYPE_NONE,
  TICKIT_TYPE_BOOL,
  TICKIT_TYPE_INT,
  TICKIT_TYPE_COLOUR,
} TickitType;

---

🌟 COMMON EVENTS 🌟

Every object instance that supports events supports the following type of event, in addition to the specific ones listed for that kind of object:

• TICKIT_..._ON_DESTROY — Invoked when the object instance is being destroyed. This will be the last time the application can use the stored data argument; it may perform any resource reclaiming operations that are required at this time. last chance bestie, use it or lose it 😭

---

🔥 EVENT FLAGS 🔥

When an event handler function is invoked, it is passed a bitmask of flags to indicate the reason for its invocation.

typedef enum {
  TICKIT_EV_FIRE,
  TICKIT_EV_UNBIND,
  TICKIT_EV_DESTROY,
} TickitEventFlags;

• TICKIT_EV_FIRE — This handler is being invoked because its associated event has occurred. The info pointer will point to a structure containing the relevant information. it's happening!! 🎉
• TICKIT_EV_UNBIND — This handler is being invoked because it is being removed from the object. This will only be observed if it was bound with the TICKIT_BIND_UNBIND flag. The info pointer will be NULL. breaking up but make it a callback 🥲
• TICKIT_EV_DESTROY — This handler is being invoked because the object instance itself is being destroyed. This will be observed if it was bound with the TICKIT_BIND_DESTROY flag, or because it is bound to the TICKIT_..._ON_DESTROY event. The info pointer will be NULL.

⚠️ heads up bestie: any event handlers for this event will be invoked in reverse order; the newest is run first and the oldest last. LIFO girlies rise 🙈

---

👑 CONTROLS 👑

A toplevel instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_setctl_int(3), and queried using tickit_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_ctl_name(3) and searched by name using tickit_ctl_lookup(3). The type of a control option can be queried using tickit_ctl_type(3). get it, set it, name it, look it up — the whole menu 💅

The options are given in an enumeration called TickitCtl. The following control values are recognised:

• TICKIT_CTL_USE_ALTSCREEN (bool) — The value is a boolean indicating whether the instance will activate the terminal alternate screen buffer mode when started. yes we're taking over the whole screen, no we're not sorry ✨

---

🫶 SEE ALSO 🫶

tickit_window(7), tickit_term(7), tickit_pen(7), tickit_rect(7), tickit_rectset(7), tickit_renderbuffer(7), tickit_string(7), tickit_utf8_count(3), tickit_version(7)

---

and that's the whole page, bestie!! 💖 This was the TICKIT(7) page from the Miscellaneous Information Manual — source/version and date live on that lil footer line at the bottom that just says TICKIT(7), and yes it's giving minimal but we respect it. go build something gorgeous in a terminal, ily, bye!! 🎀🦋✨