Provided by: libtickit-dev_0.4.3-1.1build1_amd64 bug

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

       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.

SEE ALSO

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

                                                                                 TICKIT_WINDOW(7)