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 en‐
18       tire area of the terminal. Each window allows drawing to its region  of
19       the screen by responding to an event that signifies damage to that area
20       that needs to be repainted, and has other events  that  represent  user
21       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 or‐
33       der  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 en‐
46       tirely 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  in‐
54       stance,  further sub-divided into regions using tickit_window_new(3). A
55       window instance stores a reference count to make it easier for applica‐
56       tions  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 de‐
59       stroyed. A window can also be immediately removed from its parent  with
60       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 us‐
68       ing       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_window_take_fo‐
80       cus(3), and can be queried to see if it has the focus using tickit_win‐
81       dow_is_focused(3). Windows normally  only  invoke  focus  events  about
82       themselves,  but can be made to invoke events about children windows as
83       well by using tickit_window_set_focus_child_notify(3).  When  a  window
84       has  the  input focus, the properties of the terminal cursor can be set
85       using   tickit_window_set_cursor_position(3),    tickit_window_set_cur‐
86       sor_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 re‐
97       quested 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_window_un‐
105       bind_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 in‐
114              put 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  di‐
146                     rectly to the source window; i.e. the window that handled
147                     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  visibility
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 fo‐
212              cus  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  ob‐
221       tained   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  re‐
252              ceive TICKIT_EV_FOCUS events when its child windows change focus
253              states (when true), or whether the only focus events it will re‐
254              ceive 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 re‐
258              ceive all key events on its parent first, while it is the front-
259              most  child of its parent, even before the sibling that actually
260              has input focus receives them. Additionally, the window will re‐
261              ceive all mouse events, even those outside of its geometry. This
262              option is useful when implementing popup windows  such  as  menu
263              bars.
264

SEE ALSO

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