TICKIT_WINDOW(7)

🪟 TICKIT_WINDOW(7) — windows but make it fashion 💅

okay so this is the TICKIT_WINDOW(7) page, from the Miscellaneous Information Manual, and it's literally the blueprint for every lil rectangle of screen you're ever gonna draw on in tickit. buckle up bestie 🎀

---

✨ NAME ✨

TickitWindow — a window for drawing operations and input 🖼️

---

✨ SYNOPSIS ✨

#include <tickit.h>

typedef struct TickitWindow;

---

✨ DESCRIPTION ✨

okay so a TickitWindow instance is literally just a rectangular region of the screen 🫶. and windows don't just spawn out of nowhere — they're constructed as sub-divisions of existing windows, and if you follow that chain all the way up you land on a special "root window" that represents the entire area of the terminal. every window lets you draw to its region of the screen by responding to an event that says "hey this area got damaged, repaint it pls" — and it also has other events that represent user input. that's the whole vibe 🦋

A window occupies a given size and position within its parent — the only exception being the root window, which occupies the entire terminal, main character energy, no parent required 👑. and like, conceptually a window can be placed outside the bounds of its parent (go off), but any drawing output gets clipped to the parent, and then to its parent, hierarchically, all the way to the root. also a window may be hidden, and when it is: none of its output affects the screen, and it won't receive input events either. it's giving ghost 💀

The child windows of a given parent form an ordered list, and that order can be modified. here's the tea: drawing operations on a window only actually take effect if there are no higher siblings that would obscure it. the stacking order also affects the way windows receive mouse events — a higher-level window shields lower ones from receiving an event at a given cell. so like, z-index but make it terminal ✨

Each window tracks whether a single child window has the "input focus" — that's the child window that gets informed of keyboard input events. the innermost window following the focus chain gets the first chance to react to the event, and then successively outer ones get a turn if it's still unhandled. chain of command bestie 💅

Newly-exposed areas of windows are tracked by the root window, ready to be rendered by expose events. the root window itself will expose new areas caused by terminal resizes, and the entire root window is entirely exposed initially, so your app can run its initial rendering on startup 🌈. and every window stores a TickitPen instance that can be used to apply a default style to any rendering operations that take place within it or its children. cute right 🎀

---

✨ FUNCTIONS ✨

A new top-level TickitWindow instance representing the entire terminal gets created by calling tickit_get_rootwin(3) on the toplevel Tickit instance, and then you sub-divide it into regions using tickit_window_new(3). 🫶

A window instance stores a reference count to make it easier for applications to manage the lifetime of windows. a new window starts with a count of one, and it can be adjusted using tickit_window_ref(3) and tickit_window_unref(3). when the count reaches zero the instance is destroyed. poof 💀 a window can also be immediately removed from its parent with tickit_window_close(3).

Wanna know where a window came from? the ancestry of a window can be queried using tickit_window_parent(3) and tickit_window_root(3). the stored child windows can be queried with tickit_window_children(3) and tickit_window_get_children(3). and the backing terminal can be queried with tickit_window_get_term(3). 🦋

The stacking order of a window among its siblings is yours to control using tickit_window_raise(3), tickit_window_raise_to_front(3), tickit_window_lower(3) and tickit_window_lower_to_back(3). its visibility can be controlled with tickit_window_show(3) and tickit_window_hide(3), and queried with tickit_window_is_visible(3). 👑

The position of a window within its parent can be queried using tickit_window_get_geometry(3), and its position within the terminal as a whole using tickit_window_get_abs_geometry(3). resize it with tickit_window_resize(3), move it with tickit_window_reposition(3), or do both at once with tickit_window_set_geometry(3). glow up 💅

A window can be given the input focus using tickit_window_take_focus(3), and you can query whether it has the focus using tickit_window_is_focused(3). windows normally only invoke focus events about themselves, but you can make them invoke events about children windows as well by using tickit_window_set_focus_child_notify(3). and when a window does have the input focus, the properties of the terminal cursor can be set using tickit_window_set_cursor_position(3), tickit_window_set_cursor_visible(3) and tickit_window_set_cursor_shape(3). ✨

The TickitPen instance associated with each window for drawing purposes can be obtained using tickit_window_get_pen(3), and replaced using tickit_window_set_pen(3). this pen is used during expose events, which can be requested using tickit_window_expose(3). pending expose events and other activity are performed by calling tickit_window_flush(3) on the root window instance. 🌸

While most drawing operations are performed in a deferred manner using expose events, scrolling of the terminal content can be directly requested using tickit_window_scrollrect(3), tickit_window_scroll(3) or tickit_window_scroll_with_children(3). 🌀

---

✨ EVENTS ✨

A window instance stores a list of event handlers. each event handler is associated with one event type and stores a function pointer, plus an arbitrary pointer containing user data. event handlers may be installed using tickit_window_bind_event(3) and removed using tickit_window_unbind_event_id(3). 🫶

The event types recognised are:

TICKIT_WINDOW_ON_DESTROY

The window instance is being destroyed. bye bestie 💀

TICKIT_WINDOW_ON_KEY

A key has been pressed on the keyboard while this window has input focus (or is set to steal input). info will point to a structure defined the same as the TICKIT_EV_KEY event described in tickit_term(7). ⌨️

TICKIT_WINDOW_ON_MOUSE

A mouse button has been pressed or released, the mouse cursor moved while dragging a button, or the wheel has been scrolled while the cursor is within the bounds of this window (or the window is set to steal input), or certain kinds of mouse dragging behaviour have happened. 🐭

info will point to a structure defined the same as the TICKIT_EV_MOUSE event described in tickit_term(7), except that the position given by the line and col fields will be relative to the window, rather than the terminal as a whole.

In addition to the basic mouse events found at the terminal layer, there are a few additional kinds of events that occur during mouse dragging. these give information about mouse drag motions within a window or between different windows.

• TICKIT_MOUSEEV_DRAG_START — a dragging motion has started. this event is delivered just before the TICKIT_MOUSEEV_DRAG event, and gives the original position of the mouse before it started dragging (i.e. the position of the press event).
• TICKIT_MOUSEEV_DRAG_OUTSIDE — a dragging motion that was started within this window has now moved outside it. in this case, the position given by the event will be somewhere outside the bounds of the window it is delivered to. this event is delivered directly to the source window; i.e. the window that handled the TICKIT_MOUSEEV_DRAG_START event.
• TICKIT_MOUSEEV_DRAG_DROP — a dragging motion has stopped by the mouse button being released. this event is delivered normally at the position of the mouse cursor.
• TICKIT_MOUSEEV_DRAG_STOP — a dragging motion has stopped by the mouse button being released. this event is delivered directly to the source window; i.e. the window that handled the TICKIT_MOUSEEV_DRAG_START event. if that is a different window than the one that received the TICKIT_MOUSEEV_DRAG_STOP event then the position may be outside the bounds of the window.

TICKIT_WINDOW_ON_GEOMCHANGE

At least one of the fields of the window geometry have been changed, meaning it now occupies a different area of the screen. info will point to a structure defined as:

typedef struct {
    TickitRect rect;
    TickitRect oldrect;
} TickitGeomchangeEventInfo;

rect gives the new geometry of the window relative to its parent, and oldrect gives the previous geometry. 📐

TICKIT_WINDOW_ON_EXPOSE

An area of the window needs to be re-rendered because it has now been freshly exposed; either because of stacking or visibility changes of this or sibling windows, a cascaded expose event on its parent, or due to a call to tickit_window_expose(). info will point to a structure defined as:

typedef struct {
    TickitRect rect;
    TickitRenderBuffer *rb;
} TickitExposeEventInfo;

rect gives the region of the window that needs to be redrawn. this will always be inside the window's bounds. if multiple pending regions need to be exposed, they are output in non-overlapping segments. the handling function or functions should then use the TickitRenderBuffer instance given by the rb field to draw the required contents of the window to. this instance will already be set up with the appropriate drawing pen, clipping rectangle and hole regions to account for the window hierarchy. 🎨

TICKIT_WINDOW_ON_FOCUS

This window has either gained or lost the input focus, or a child of it has, if this window is set to also notify on that case by using tickit_window_set_focus_child_notify(). info will point to a structure defined as:

typedef struct {
    TickitFocusEventType type;
    TickitWindow *win;
} TickitFocusEventInfo;

type takes one of the values TICKIT_FOCUSEV_IN or TICKIT_FOCUSEV_OUT. win will normally be the window that is invoking the event, except for the case of notifications about child windows, where it will indicate which child has changed focus. when a focus change happens, the window losing focus receives its TICKIT_FOCUSEV_OUT event before the window gaining it receives its TICKIT_FOCUSEV_IN. ✨

---

🎛️ CONTROLS 🎛️

okay bestie so a window instance has a whole lil collection of runtime-configuration control options that change how it behaves ✨ These are the vibes you can toggle while it's alive.

You set them with tickit_window_setctl_int(3) and you ask about them with tickit_window_getctl_int(3). Every single control has a human-readable string name — grab one with tickit_windowctl_name(3), or hunt one down by its name using tickit_windowctl_lookup(3). And if you wanna know what type a control option is? That's tickit_windowctl_type(3), easy 💅

All of these live in one enum called TickitWindowCtl. Here's the whole roster, no skips, no cuts:

• TICKIT_WINCTL_CURSORBLINK (bool) — the value is a boolean saying whether the terminal's text cursor should blink while this window is the one holding the input focus. Blinky cursor era 🫶
• TICKIT_WINCTL_CURSORSHAPE (int) — the value is an integer from the TickitCursorShape enumeration, and it tells the terminal what shape its text cursor should be while this window has the input focus. The options are:
  • TICKIT_CURSORSHAPE_BLOCK — a solid block filling the entire cell. classic. iconic. takes up the whole room 🧱
  • TICKIT_CURSORSHAPE_UNDER — an underline below the character. subtle, lowkey, demure ✨
  • TICKIT_CURSORSHAPE_LEFT_BAR — a vertical bar to the left of the character. main character standing off to the side fr 💅
• TICKIT_WINCTL_CURSORVIS (bool) — a boolean for whether the terminal's text cursor should be visible while this window has the input focus. (yes bestie, visible and blinking are two different toggles, keep up 😭)
• TICKIT_WINCTL_FOCUS_CHILD_NOTIFY (bool) — a boolean that decides whether the window gets TICKIT_EV_FOCUS events when its child windows change focus states (that's true), or whether the only focus events it receives are the ones about itself directly (that's false). so: nosy parent mode vs. minding-your-business mode 🍓
• TICKIT_WINCTL_STEAL_INPUT (bool) — a boolean saying whether the window receives all key events on its parent first, while it's the front-most child of its parent — and yes, before the sibling that actually has input focus gets them 👑 On top of that, the window will receive all mouse events too, even the ones outside of its geometry. this is the one you want when you're building popup windows like menu bars, fr fr. it is literally named "steal input," what more do you want 💀

---

🌈 SEE ALSO 🌈

go read these next, they're all part of the same little universe:

• tickit(7)
• tickit_term(7)
• tickit_renderbuffer(7)
• tickit_rect(7)

---

and that's a wrap on TICKIT_WINDOW(7) bestie 💖 that footer down at the bottom is just the page signing its own name — TICKIT_WINDOW(7) — so consider this your official goodbye kiss from the manual. go forth and move some windows around 🎀🦋✨