Debian Codegraph @

vendor/lwd/nottui/nottui.mli

raw
1 open Notty
2
3 (**
4 Nottui augments Notty with primitives for laying out user interfaces (in the
5 terminal) and reacting to input events.
6 *)
7
8 (** {1 Focus (defining and managing active objects)} *)
9
10 module Focus :
11 sig
12
13 type handle
14 (** A [handle] represents a primitive area that can request, receive and lose
15 the focus. A visible UI is made of many handles, of which at most one can
16 be active. *)
17
18 val make : unit -> handle
19 (** Create a new handle *)
20
21 val request : handle -> unit
22 (** Request the focus *)
23
24 val release : handle -> unit
25 (** Release the focus (if the handle has it) *)
26
27 type status
28 (** [status] represents the state in which a handle can be.
29 Externally we care about having or not the focus, which can be queried
30 with the [has_focus] function. Internally, [status] also keeps track of
31 conflicts (if multiple handles [request]ed the focus).
32 *)
33
34 val empty : status
35 (** A status that has no focus and no conflicts *)
36
37 val status : handle -> status Lwd.t
38 (** Get the status of a focus [handle]. The [status] is a reactive value:
39 it will evolve over time, as focus is received or lost. *)
40
41 val has_focus : status -> bool
42 (** Check if this [status] corresponds to an active focus *)
43
44 (** TODO
45 This implements a more general concept of "reactive auction":
46
47 - multiple parties are competing for a single resource (focus here, but
48 for instance a tab component can only display a single tab among many).
49
50 - the result can evolve over time, parties can join or leave, or bid
51 "more".
52 *)
53 end
54
55 (** {1 Gravity (horizontal and vertical alignments)} *)
56
57 module Gravity :
58 sig
59
60 type direction = [
61 | `Negative
62 | `Neutral
63 | `Positive
64 ]
65 (** A gravity is a pair of directions along the horizontal and vertical
66 axis.
67
68 Horizontal axis goes from left to right and vertical axis from top to
69 bottom.
70
71 [`Negative] direction means left / top bounds, [`Neutral] means center
72 and [`Positive] means right / bottom.
73 *)
74
75 val pp_direction : Format.formatter -> direction -> unit
76 (** Printing directions *)
77
78 type t
79 (** The gravity type is a pair of an horizontal and a vertical gravity *)
80
81 val pp : Format.formatter -> t -> unit
82 (** Printing gravities *)
83
84 val make : h:direction -> v:direction -> t
85 (** Make a gravity value from an [h]orizontal and a [v]ertical directions. *)
86
87 val default : t
88 (** Default (negative, aligning to the top-left) gravity. *)
89
90 val h : t -> direction
91 (** Get the horizontal direction *)
92
93 val v : t -> direction
94 (** Get the vertical direction *)
95
96 end
97
98 type gravity = Gravity.t
99
100 (** {1 Primitive combinators for making user interfaces} *)
101
102 module Ui :
103 sig
104
105 type t
106 (* Type of UI elements *)
107
108 val pp : Format.formatter -> t -> unit
109 (** Printing UI element *)
110
111 (** {1 Layout specifications} *)
112
113 type layout_spec = { w : int; h : int; sw : int; sh : int; }
114 (** The type of layout specifications.
115
116 For each axis, layout is specified as a pair of integers:
117 - a fixed part that is expressed as a number of columns or rows
118 - a stretchable part that represents a strength used to share the
119 remaining space (or 0 if the UI doesn't extend over free space)
120 *)
121
122 val pp_layout_spec : Format.formatter -> layout_spec -> unit
123 (** Printing layout specification *)
124
125 val layout_spec : t -> layout_spec
126 (** Get the layout spec for an UI element *)
127
128 val layout_width : t -> int
129 (** Get the layout width component of an UI element *)
130
131 val layout_stretch_width : t -> int
132 (** Get the layout stretch width strength of an UI element *)
133
134 val layout_height : t -> int
135 (** Get the layout height component of an UI element *)
136
137 val layout_stretch_height : t -> int
138 (** Get the layout height strength of an UI element *)
139
140 (** {1 Primitive images} *)
141
142 val empty : t
143 (** The empty surface: it occupies no space and does not do anything *)
144
145 val atom : image -> t
146 (** Primitive surface that displays a Notty image *)
147
148 val space : int -> int -> t
149 (** Void space of dimensions [x,y]. Useful for padding and interstitial
150 space. *)
151
152 (** {1 Event handles} *)
153
154 type may_handle = [ `Unhandled | `Handled ]
155 (** An event is propagated until it gets handled.
156 Handler functions return a value of type [may_handle] to indicate
157 whether the event was handled or not. *)
158
159 type mouse_handler = x:int -> y:int -> Unescape.button -> [
160 | may_handle
161 | `Grab of (x:int -> y:int -> unit) * (x:int -> y:int -> unit)
162 ]
163 (** The type of handlers for mouse events. They receive the (absolute)
164 coordinates of the mouse, the button that was clicked.
165
166 In return they indicate whether the event was handled or if the mouse is
167 "grabbed".
168
169 When grabbed, two functions [on_move] and [on_release] should be
170 provided. The [on_move] function will be called when the mouse move while
171 the button is pressed and the [on_release] function is called when the
172 button is released.
173
174 During that time, no other mouse input events can be dispatched.
175 *)
176
177 type semantic_key = [
178 (* Clipboard *)
179 | `Copy
180 | `Paste
181 (* Focus management *)
182 | `Focus of [`Next | `Prev | `Left | `Right | `Up | `Down]
183 ]
184 (** Key handlers normally reacts to keyboard input but a few special keys are
185 defined to represent higher-level actions.
186 Copy and paste, as well as focus movements. *)
187
188 type key = [
189 | Unescape.special | `Uchar of Uchar.t | `ASCII of char | semantic_key
190 ] * Unescape.mods
191 (** A key is the pair of a main key and a list of modifiers *)
192
193 type mouse = Unescape.mouse
194 (** Specification of mouse inputs, taken from Notty *)
195
196 type event = [ `Key of key | `Mouse of mouse | `Paste of Unescape.paste ]
197 (* The type of input events. *)
198
199 val mouse_area : mouse_handler -> t -> t
200 (** Handle mouse events that happens over an ui. *)
201
202 val keyboard_area : ?focus:Focus.status -> (key -> may_handle) -> t -> t
203 (** Define a focus receiver, handle keyboard events over the focused area *)
204
205 val has_focus : t -> bool
206 (** Check if this UI has focus, either directly (it is a focused
207 [keyboard_area]), or inherited (one of the child is a focused
208 [keyboard_area]). *)
209
210 val event_filter :
211 ?focus:Focus.status ->
212 ([`Key of key | `Mouse of mouse] -> may_handle) -> t -> t
213 (** A hook that intercepts and can interrupt events when they reach a
214 sub-part of the UI. *)
215
216 (** {1 Sensors}
217
218 Sensors are used to observe the physical dimensions after layout has been
219 resolved.
220 *)
221
222 type size_sensor = w:int -> h:int -> unit
223 (** The size sensor callback tells you the [w]idth and [h]eight of UI.
224 The sensor is invoked only when the UI is visible. *)
225
226 val size_sensor : size_sensor -> t -> t
227 (** Attach a size sensor to an image *)
228
229 type frame_sensor = x:int -> y:int -> w:int -> h:int -> unit -> unit
230 (** The frame sensor callback gives you the whole rectangle where the widget
231 is displayed.
232
233 The first for components are applied during before visiting children,
234 the last unit is applied after visiting children.
235 *)
236
237 val transient_sensor : frame_sensor -> t -> t
238 (** Attach a transient frame sensor: the callback will be invoked only once,
239 on next frame. *)
240
241 val permanent_sensor : frame_sensor -> t -> t
242 (** Attach a permanent sensor: the callback will be invoked on every frame.
243 Note that this can have a significant impact on performance. *)
244
245 (** {1 Composite images} *)
246
247 val resize :
248 ?w:int -> ?h:int -> ?sw:int -> ?sh:int ->
249 ?pad:Gravity.t -> ?crop:Gravity.t -> ?bg:attr -> t -> t
250 (** Override the layout specification of an image with provided [w], [h],
251 [sw] or [sh].
252
253 [pad] and [crop] are used to determine how to align the UI when there is
254 too much or not enough space.
255
256 [bg] is used to fill the padded background.
257 *)
258
259 val resize_to :
260 layout_spec ->
261 ?pad:Gravity.t -> ?crop:Gravity.t -> ?bg:attr -> t -> t
262
263 val shift_area : int -> int -> t -> t
264 (** Shift the contents of a UI by a certain amount.
265 Positive values crop the image while negative values pad.
266
267 This primitive is used to implement scrolling.
268 *)
269
270 val join_x : t -> t -> t
271 (** Horizontally join two images *)
272
273 val join_y : t -> t -> t
274 (** Vertically join two images *)
275
276 val join_z : t -> t -> t
277 (** Superpose two images. The right one will be on top. *)
278
279 val pack_x : t Lwd_utils.monoid
280 (** Horizontal concatenation monoid *)
281
282 val pack_y : t Lwd_utils.monoid
283 (** Vertical concatenation monoid *)
284
285 val pack_z : t Lwd_utils.monoid
286 (** Superposition monoid *)
287
288 val hcat : t list -> t
289 (** Short-hand for horizontally joining a list of images *)
290
291 val vcat : t list -> t
292 (** Short-hand for vertically joining a list of images *)
293
294 val zcat : t list -> t
295 (** Short-hand for superposing a list of images *)
296 end
297
298 type ui = Ui.t
299
300 (** {1 Rendering user interfaces and dispatching input events} *)
301
302 module Renderer :
303 sig
304
305 type t
306 (** The type of a renderer *)
307
308 type size = int * int
309 (** Size of a rendering surface, as a pair of width and height *)
310
311 val make : unit -> t
312 (** Create a new renderer.
313
314 It maintains state to update output image and to dispatch events. *)
315
316 val update : t -> size -> Ui.t -> unit
317 (** Update the contents to be rendered to the given UI at a specific size *)
318
319 val size : t -> size
320 (** Get the size of the last update *)
321
322 val image : t -> image
323 (** Render and return actual image *)
324
325 val dispatch_mouse : t -> Ui.mouse -> Ui.may_handle
326 (** Dispatch a mouse event *)
327
328 val dispatch_key : t -> Ui.key -> Ui.may_handle
329 (** Dispatch a keyboard event *)
330
331 val dispatch_event : t -> Ui.event -> Ui.may_handle
332 (** Dispatch an event *)
333
334 end
335
336 (** {1 Main loop}
337
338 Outputting an interface to a TTY and interacting with it
339 *)
340
341 module Ui_loop :
342 sig
343 open Notty_unix
344
345 val step : ?process_event:bool -> ?timeout:float -> renderer:Renderer.t ->
346 Term.t -> ui Lwd.root -> unit
347 (** Run one step of the main loop.
348
349 Update output image describe by the provided [root].
350 If [process_event], wait up to [timeout] seconds for an input event, then
351 consume and dispatch it. *)
352
353 val run :
354 ?tick_period:float -> ?tick:(unit -> unit) ->
355 ?term:Term.t -> ?renderer:Renderer.t ->
356 ?quit:bool Lwd.var -> ?quit_on_escape:bool ->
357 ?quit_on_ctrl_q:bool -> ui Lwd.t -> unit
358 (** Repeatedly run steps of the main loop, until either:
359 - [quit] becomes true,
360 - the ui computation raises an exception,
361 - if [quit_on_ctrl_q] was true or not provided, wait for Ctrl-Q event
362 - if [quit_on_escape] was true or not provided, wait for Escape event
363
364 Specific [term] or [renderer] instances can be provided, otherwise new
365 ones will be allocated and released.
366
367 To simulate concurrency in a polling fashion, tick function and period
368 can be provided. Use the [Lwt] backend for real concurrency.
369 *)
370 end