1TICKIT_WINDOW(7) Miscellaneous Information Manual TICKIT_WINDOW(7)
2
6 TickitWindow - a window for drawing operations and input
7
9 #include <tickit.h>
10 typedef struct TickitWindow;
12
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 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 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 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 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
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 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 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 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 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 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 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
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 The event types recognised are:
108 TICKIT_WINDOW_ON_DESTROY
110 The window instance is being destroyed.
111 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 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 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 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 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 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 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 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 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 typedef struct {
169 TickitRect rect;
170 TickitRect oldrect;
171 } TickitGeomchangeEventInfo;
172 rect gives the new geometry of the window relative to its par‐
174 ent, and oldrect gives the previous geometry.
175 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 typedef struct {
184 TickitRect rect;
185 TickitRenderBuffer *rb;
186 } TickitExposeEventInfo;
187 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 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 typedef struct {
204 TickitFocusEventType type;
205 TickitWindow *win;
206 } TickitFocusEventInfo;
207 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
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 The options are given in an enumeration called TickitWindowCtl. The
226 following control values are recognised:
227 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 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 TICKIT_CURSORSHAPE_BLOCK
238 A solid block filling the entire cell.
239 TICKIT_CURSORSHAPE_UNDER
241 An underline below the character.
242 TICKIT_CURSORSHAPE_LEFT_BAR
244 A vertical bar to the left of the character.
245 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 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 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
266 tickit(7), tickit_term(7), tickit_renderbuffer(7), tickit_rect(7)
267 TICKIT_WINDOW(7)