tickit_window - Man Page

#include <tickit.h>

typedef struct TickitWindow;

A TickitWindow instance represents a rectangular region of the screen. Windows are constructed as sub-divisions of existing windows, ultimately coming from a special "root window" is that represents the entire area of the terminal. Each window allows drawing to its region of the screen by responding to an event that signifies damage to that area that needs to be repainted, and has other events that represent user input.

A window occupies a given size and position within its parent (apart from the root window, which occupies the entire terminal). Conceptually a window can be placed outside of the bounds of its parent, though any drawing output is clipped to the parent (and its parent, hierarchially, all the way to the root). A window may be hidden, at which point none of its output affects the screen, nor will it receive input events.

The child windows of a given parent form an ordered list, the order of which can be modified. Drawing operations on a window only take effect if there are no higher siblings that would obscure it. The stacking order also affects the way that windows receive mouse events, with higher-level window shielding lower ones from receiving an event at a given cell.

Each window tracks whether a single child window has the "input focus"; this is the child window that will be informed of keyboard input events. The innermost window following the focus chain gets the first chance to react to the event, followed by successively outer ones if it remains unhandled.

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, to allow the application to run its initial rendering on startup. Each 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.

A new top-level TickitWindow instance to represent the entire terminal is created by calling tickit_get_rootwin(3) on the toplevel Tickit instance, further sub-divided 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. A window can also be immediately removed from its parent with tickit_window_close(3).

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 by using tickit_window_children(3) and tickit_window_get_children(3). The backing terminal can be queried with tickit_window_get_term(3).

The stacking order of a window among its siblings can be controlled 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 using tickit_window_show(3) and tickit_window_hide(3), and queried using tickit_window_is_visible(3).

The position of a window within its parent can be queried using tickit_window_get_geometry(3) and within the terminal as a whole using tickit_window_get_abs_geometry(3). It can be resized using tickit_window_resize(3), moved using tickit_window_reposition(3), or both using tickit_window_set_geometry(3).

A window can be given the input focus using tickit_window_take_focus(3), and can be queried to see if it has the focus using tickit_window_is_focused(3). Windows normally only invoke focus events about themselves, but can be made to invoke events about children windows as well by using tickit_window_set_focus_child_notify(3). When a window has 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).

A window instance stores a list of event handlers. Each event handler is associated with one event type and stores a function pointer, and 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.

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 an 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 onw 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.

A window instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_window_setctl_int(3), and queried using tickit_window_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_windowctl_name(3) and searched by name using tickit_windowctl_lookup(3). The type of a control option can be queried using tickit_windowctl_type(3).

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

TICKIT_WINCTL_CURSORBLINK (bool)

The value is a boolean indicating whether the terminal text cursor should blink while this window has the input focus.

TICKIT_WINCTL_CURSORSHAPE (int)

The value is an integer from the TickitCursorShape enumeration indicating what shape the terminal's text cursor should be while this window has the input focus. Values are:

TICKIT_CURSORSHAPE_BLOCK

A solid block filling the entire cell.

TICKIT_CURSORSHAPE_UNDER

An underline below the character.

TICKIT_CURSORSHAPE_LEFT_BAR

A vertical bar to the left of the character.

TICKIT_WINCTL_CURSORVIS (bool)

The value is a boolean indicating whether the terminal text cursor should be visible while this window has the input focus.

TICKIT_WINCTL_FOCUS_CHILD_NOTIFY (bool)

The value is a boolean indicating whether the window will receive TICKIT_EV_FOCUS events when its child windows change focus states (when true), or whether the only focus events it will receive are ones relating to itself directly (when false).

TICKIT_WINCTL_STEAL_INPUT (bool)

The value is a boolean indicating whether the window will receive all key events on its parent first, while it is the front-most child of its parent, even before the sibling that actually has input focus receives them. Additionally, the window will receive all mouse events, even those outside of its geometry. This option is useful when implementing popup windows such as menu bars.

tickit(7), tickit_term(7), tickit_renderbuffer(7), tickit_rect(7)

tickit(7), tickit_debug(7), tickit_get_rootwin(3), tickit_window_bind_event(3), tickit_window_children(3), tickit_window_close(3), tickit_windowctl_name(3), tickit_window_destroy(3), tickit_window_expose(3), tickit_window_flush(3), tickit_window_get_abs_geometry(3), tickit_window_get_geometry(3), tickit_window_get_pen(3), tickit_window_get_term(3), tickit_window_new(3), tickit_window_new_root(3), tickit_window_parent(3), tickit_window_raise(3), tickit_window_ref(3), tickit_window_scroll(3), tickit_window_setctl_int(3), tickit_window_set_cursor_position(3), tickit_window_set_focus_child_notify(3), tickit_window_set_geometry(3), tickit_window_set_steal_input(3), tickit_window_show(3), tickit_window_take_focus(3).