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