1TICKIT_WINDOW(7)       Miscellaneous Information Manual       TICKIT_WINDOW(7)
2
3
4

NAME

6       TickitWindow - a window for drawing operations and input
7

SYNOPSIS

9       #include <tickit.h>
10
11       typedef struct TickitWindow;
12
13

DESCRIPTION

15       A  TickitWindow instance represents a rectangular region of the screen.
16       Windows are constructed as sub-divisions  of  existing  windows,  ulti‐
17       mately  coming  from  a  special  "root  window" is that represents the
18       entire area of the terminal. Each window allows drawing to  its  region
19       of  the  screen by responding to an event that signifies damage to that
20       area that needs to be repainted, and has other  events  that  represent
21       user input.
22
23       A  window  occupies  a given size and position within its parent (apart
24       from the root window, which occupies the entire terminal). Conceptually
25       a  window can be placed outside of the bounds of its parent, though any
26       drawing output is clipped to the parent (and its parent, hierarchially,
27       all  the  way to the root). A window may be hidden, at which point none
28       of its output affects the screen, nor will it receive input events.
29
30       The child windows of a given parent form an ordered list, the order  of
31       which  can be modified. Drawing operations on a window only take effect
32       if there are no higher siblings that would  obscure  it.  The  stacking
33       order  also  affects  the  way  that windows receive mouse events, with
34       higher-level window shielding lower ones from receiving an event  at  a
35       given cell.
36
37       Each window tracks whether a single child window has the "input focus";
38       this is the child window  that  will  be  informed  of  keyboard  input
39       events.  The  innermost window following the focus chain gets the first
40       chance to react to the event, followed by successively outer ones if it
41       remains unhandled.
42
43       Newly-exposed areas of windows are tracked by the root window, ready to
44       be rendered by expose events. The root window itself  will  expose  new
45       areas  caused  by  terminal  resizes,  and  the  entire  root window is
46       entirely exposed initially, to allow the application to run its initial
47       rendering  on startup. Each window stores a TickitPen instance that can
48       be used to apply a default style to any rendering operations that  take
49       place within it or its children.
50

FUNCTIONS

52       A  new top-level TickitWindow instance to represent the entire terminal
53       is created by calling  tickit_get_rootwin(3)  on  the  toplevel  Tickit
54       instance,  further sub-divided into regions using tickit_window_new(3).
55       A window instance stores a reference count to make it easier for appli‐
56       cations  to  manage the lifetime of windows. A new window starts with a
57       count of one, and it can be  adjusted  using  tickit_window_ref(3)  and
58       tickit_window_unref(3).  When  the  count  reaches zero the instance is
59       destroyed. A window can also be immediately  removed  from  its  parent
60       with tickit_window_close(3).
61
62       The  ancestry  of a window can be queried using tickit_window_parent(3)
63       and tickit_window_root(3). The stored child windows can be  queried  by
64       using  tickit_window_children(3) and tickit_window_get_children(3). The
65       backing terminal can be queried with tickit_window_get_term(3).
66
67       The stacking order of a window among its  siblings  can  be  controlled
68       using      tickit_window_raise(3),     tickit_window_raise_to_front(3),
69       tickit_window_lower(3) and tickit_window_lower_to_back(3). Its visibil‐
70       ity  can  be  controlled  using  tickit_window_show(3)  and tickit_win‐
71       dow_hide(3), and queried using tickit_window_is_visible(3).
72
73       The position of a  window  within  its  parent  can  be  queried  using
74       tickit_window_get_geometry(3)  and within the terminal as a whole using
75       tickit_window_get_abs_geometry(3). It can be resized using  tickit_win‐
76       dow_resize(3),  moved  using tickit_window_reposition(3), or both using
77       tickit_window_set_geometry(3).
78
79       A  window  can   be   given   the   input   focus   using   tickit_win‐
80       dow_take_focus(3),  and can be queried to see if it has the focus using
81       tickit_window_is_focused(3). Windows normally only invoke focus  events
82       about  themselves, but can be made to invoke events about children win‐
83       dows as well by using tickit_window_set_focus_child_notify(3).  When  a
84       window  has  the input focus, the properties of the terminal cursor can
85       be   set   using   tickit_window_set_cursor_position(3),    tickit_win‐
86       dow_set_cursor_visible(3) and tickit_window_set_cursor_shape(3).
87
88       The TickitPen instance associated with each window for drawing purposes
89       can be obtained  using  tickit_window_get_pen(3),  and  replaced  using
90       tickit_window_set_pen(3).  This pen is used during expose events, which
91       can be requested using tickit_window_expose(3). Pending  expose  events
92       and  other  activity are performed by calling tickit_window_flush(3) on
93       the root window instance.
94
95       While most drawing operations are performed in a deferred manner  using
96       expose  events,  scrolling  of  the  terminal  content  can be directly
97       requested using tickit_window_scrollrect(3), tickit_window_scroll(3) or
98       tickit_window_scroll_with_children(3).
99

EVENTS

101       A  window  instance stores a list of event handlers. Each event handler
102       is associated with one event type and stores a function pointer, and an
103       arbitrary pointer containing user data. Event handlers may be installed
104       using  tickit_window_bind_event(3)  and   removed   using   tickit_win‐
105       dow_unbind_event_id(3).
106
107       The event types recognised are:
108
109       TICKIT_WINDOW_ON_DESTROY
110              The window instance is being destroyed.
111
112       TICKIT_WINDOW_ON_KEY
113              A  key  has  been  pressed on the keyboard while this window has
114              input focus (or is set to steal input). info  will  point  to  a
115              structure  defined the same as the TICKIT_EV_KEY event described
116              in tickit_term(7).
117
118       TICKIT_WINDOW_ON_MOUSE
119              A mouse button has been pressed or released,  the  mouse  cursor
120              moved  while  dragging  a button, or the wheel has been scrolled
121              while the cursor is within the bounds of  this  window  (or  the
122              window  is  set to steal input), or certain kinds of mouse drag‐
123              ging behaviour have happened.
124
125              info  will  point  to  a  structure  defined  the  same  as  the
126              TICKIT_EV_MOUSE  event  described in tickit_term(7), except that
127              the position given by the line and col fields will  be  relative
128              to the window, rather than the terminal as a whole.
129
130              In  addition  to  the  basic  mouse events found at the terminal
131              layer, there are a few additional kinds  of  events  that  occur
132              during  mouse  dragging. These give information about mouse drag
133              motions within a window or between different windows.
134
135              TICKIT_MOUSEEV_DRAG_START
136                     A dragging motion has started. This  event  is  delivered
137                     just  before the TICKIT_MOUSEEV_DRAG event, and gives the
138                     original position of the mouse before it started dragging
139                     (i.e. the position of the press event).
140
141              TICKIT_MOUSEEV_DRAG_OUTSIDE
142                     A dragging motion that was started within this window has
143                     now moved outside it. In this case, the position given by
144                     the  event  will  be  somewhere outside the bounds of the
145                     window it  is  delivered  to.  This  event  is  delivered
146                     directly  to the source window; i.e. the window that han‐
147                     dled the TICKIT_MOUSEEV_DRAG_START event.
148
149              TICKIT_MOUSEEV_DRAG_DROP
150                     A dragging motion has stopped by the mouse  button  being
151                     released.  This  event is delivered normally at the posi‐
152                     tion of the mouse cursor.
153
154              TICKIT_MOUSEEV_DRAG_STOP
155                     A dragging motion has stopped by the mouse  button  being
156                     released.  This event is delivered directly to the source
157                     window;   i.e.    the    window    that    handled    the
158                     TICKIT_MOUSEEV_DRAG_START  event.  If that is a different
159                     window    than    the    one    that     received     the
160                     TICKIT_MOUSEEV_DRAG_STOP  event  then the position may be
161                     outside the bounds of the window.
162
163       TICKIT_WINDOW_ON_GEOMCHANGE
164              At least one of the fields of  the  window  geometry  have  been
165              changed, meaning it now occupies a different area of the screen.
166              info will point to a structure defined as:
167
168              typedef struct {
169                  TickitRect rect;
170                  TickitRect oldrect;
171              } TickitGeomchangeEventInfo;
172
173              rect gives the new geometry of the window relative to  its  par‐
174              ent, and oldrect gives the previous geometry.
175
176       TICKIT_WINDOW_ON_EXPOSE
177              An area of the window needs to be re-rendered because it has now
178              been freshly exposed; either because of  stacking  or  visibilty
179              changes  of  this or sibling windows, a cascaded expose event on
180              its parent, or due to a  call  to  tickit_window_expose().  info
181              will point to a structure defined as:
182
183              typedef struct {
184                  TickitRect rect;
185                  TickitRenderBuffer *rb;
186              } TickitExposeEventInfo;
187
188              rect  gives  the  region of the window that needs to be redrawn.
189              This will always be inside  the  window's  bounds.  If  multiple
190              pending regions need to be exposed, they are output in non-over‐
191              lapping segments. The handling function or functions should then
192              use  the  TickitRenderBuffer  instance  given by the rb field to
193              draw the required contents of the window to. This instance  will
194              already  be  set  up  with the appropriate drawing pen, clipping
195              rectangle and hole regions to account for the window hierarchy.
196
197       TICKIT_WINDOW_ON_FOCUS
198              This window has either gained or lost  the  input  focus,  or  a
199              child  of  it  has  an this window is set to also notify on that
200              case by using tickit_window_set_focus_child_notify(). info  will
201              point to a structure defined as:
202
203              typedef struct {
204                  TickitFocusEventType type;
205                  TickitWindow *win;
206              } TickitFocusEventInfo;
207
208              type  takes  onw of the values TICKIT_FOCUSEV_IN or TICKIT_FOCU‐
209              SEV_OUT. win will normally be the window that  is  invoking  the
210              event, except for the case of notifications about child windows,
211              where it will indicate which child has  changed  focus.  When  a
212              focus  change  happens,  the  window  losing  focus receives its
213              TICKIT_FOCUSEV_OUT event before the window gaining  it  receives
214              its TICKIT_FOCUSEV_IN.
215

CONTROLS

217       A window instance has a number of runtime-configuration control options
218       that  affect  its  behaviour.  These  can  be  set  using   tickit_win‐
219       dow_setctl_int(3),  and  queried using tickit_window_getctl_int(3). The
220       individual controls  have  human-readable  string  names  that  can  be
221       obtained   by  tickit_window_ctlname(3)  and  searched  by  name  using
222       tickit_window_lookup_ctl(3). The  type  of  a  control  option  can  be
223       queried using tickit_window_ctltype(3).
224
225       The  options  are  given  in an enumeration called TickitWindowCtl. The
226       following control values are recognised:
227
228       TICKIT_WINCTL_CURSORBLINK (bool)
229              The value is a boolean indicating whether the terminal text cur‐
230              sor should blink while this window has the input focus.
231
232       TICKIT_WINCTL_CURSORSHAPE (int)
233              The  value  is an integer from the TickitCursorShape enumeration
234              indicating what shape the terminal's text cursor should be while
235              this window has the input focus. Values are:
236
237              TICKIT_CURSORSHAPE_BLOCK
238                     A solid block filling the entire cell.
239
240              TICKIT_CURSORSHAPE_UNDER
241                     An underline below the character.
242
243              TICKIT_CURSORSHAPE_LEFT_BAR
244                     A vertical bar to the left of the character.
245
246       TICKIT_WINCTL_CURSORVIS (bool)
247              The value is a boolean indicating whether the terminal text cur‐
248              sor should be visible while this window has the input focus.
249
250       TICKIT_WINCTL_FOCUS_CHILD_NOTIFY (bool)
251              The value is  a  boolean  indicating  whether  the  window  will
252              receive  TICKIT_EV_FOCUS  events  when  its child windows change
253              focus states (when true), or whether the only  focus  events  it
254              will receive are ones relating to itself directly (when false).
255
256       TICKIT_WINCTL_STEAL_INPUT (bool)
257              The  value  is  a  boolean  indicating  whether  the window will
258              receive all key events on its parent  first,  while  it  is  the
259              front-most  child  of  its  parent, even before the sibling that
260              actually has input focus receives them. Additionally, the window
261              will  receive all mouse events, even those outside of its geome‐
262              try. This option is useful when implementing popup windows  such
263              as menu bars.
264

SEE ALSO

266       tickit(7), tickit_term(7), tickit_renderbuffer(7), tickit_rect(7)
267
268
269
270                                                              TICKIT_WINDOW(7)
Impressum