Ubuntu Manpage: TickitWindow - a window for drawing operations and input

Provided by: libtickit-dev_0.4.3-1.1build1_amd64

NAME

       TickitWindow - a window for drawing operations and input

SYNOPSIS

       #include <tickit.h>

       typedef struct TickitWindow;

DESCRIPTION

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.

FUNCTIONS

       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).

EVENTS

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.

CONTROLS

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).