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