Module Nottui.Ui

type t
val pp : Stdlib.Format.formatter -> t -> unit

Printing UI element

Layout specifications

type layout_spec = {
w : int;
h : int;
sw : int;
sh : int;
}

The type of layout specifications.

For each axis, layout is specified as a pair of integers:

  • a fixed part that is expressed as a number of columns or rows
  • a stretchable part that represents a strength used to share the remaining space (or 0 if the UI doesn't extend over free space)
val pp_layout_spec : Stdlib.Format.formatter -> layout_spec -> unit

Printing layout specification

val layout_spec : t -> layout_spec

Get the layout spec for an UI element

val layout_width : t -> int

Get the layout width component of an UI element

val layout_stretch_width : t -> int

Get the layout stretch width strength of an UI element

val layout_height : t -> int

Get the layout height component of an UI element

val layout_stretch_height : t -> int

Get the layout height strength of an UI element

Primitive images

val empty : t

The empty surface: it occupies no space and does not do anything

val atom : Notty.image -> t

Primitive surface that displays a Notty image

val space : int -> int -> t

Void space of dimensions x,y. Useful for padding and interstitial space.

Event handles

type may_handle = [
| `Unhandled
| `Handled
]

An event is propagated until it gets handled. Handler functions return a value of type may_handle to indicate whether the event was handled or not.

type mouse_handler = x:int -> y:int -> Notty.Unescape.button -> [ may_handle | `Grab of ( x:int -> y:int -> unit ) * ( x:int -> y:int -> unit ) ]

The type of handlers for mouse events. They receive the (absolute) coordinates of the mouse, the button that was clicked.

In return they indicate whether the event was handled or if the mouse is "grabbed".

When grabbed, two functions on_move and on_release should be provided. The on_move function will be called when the mouse move while the button is pressed and the on_release function is called when the button is released.

During that time, no other mouse input events can be dispatched.

type semantic_key = [
| `Copy
| `Paste
| `Focus of [ `Next | `Prev | `Left | `Right | `Up | `Down ]
]

Key handlers normally reacts to keyboard input but a few special keys are defined to represent higher-level actions. Copy and paste, as well as focus movements.

type key = [ Notty.Unescape.special | `Uchar of Stdlib.Uchar.t | `ASCII of char | semantic_key ] * Notty.Unescape.mods

A key is the pair of a main key and a list of modifiers

type mouse = Notty.Unescape.mouse

Specification of mouse inputs, taken from Notty

type event = [
| `Key of key
| `Mouse of mouse
| `Paste of Notty.Unescape.paste
]
val mouse_area : mouse_handler -> t -> t

Handle mouse events that happens over an ui.

val keyboard_area : ?focus:Focus.status -> ( key -> may_handle ) -> t -> t

Define a focus receiver, handle keyboard events over the focused area

val has_focus : t -> bool

Check if this UI has focus, either directly (it is a focused keyboard_area), or inherited (one of the child is a focused keyboard_area).

val event_filter : ?focus:Focus.status -> ( [ `Key of key | `Mouse of mouse ] -> may_handle ) -> t -> t

A hook that intercepts and can interrupt events when they reach a sub-part of the UI.

Sensors

Sensors are used to observe the physical dimensions after layout has been resolved.

type size_sensor = w:int -> h:int -> unit

The size sensor callback tells you the width and height of UI. The sensor is invoked only when the UI is visible.

val size_sensor : size_sensor -> t -> t

Attach a size sensor to an image

type frame_sensor = x:int -> y:int -> w:int -> h:int -> unit -> unit

The frame sensor callback gives you the whole rectangle where the widget is displayed.

The first for components are applied during before visiting children, the last unit is applied after visiting children.

val transient_sensor : frame_sensor -> t -> t

Attach a transient frame sensor: the callback will be invoked only once, on next frame.

val permanent_sensor : frame_sensor -> t -> t

Attach a permanent sensor: the callback will be invoked on every frame. Note that this can have a significant impact on performance.

Composite images

val resize : ?w:int -> ?h:int -> ?sw:int -> ?sh:int -> ?pad:Gravity.t -> ?crop:Gravity.t -> ?bg:Notty.attr -> t -> t

Override the layout specification of an image with provided w, h, sw or sh.

pad and crop are used to determine how to align the UI when there is too much or not enough space.

bg is used to fill the padded background.

val resize_to : layout_spec -> ?pad:Gravity.t -> ?crop:Gravity.t -> ?bg:Notty.attr -> t -> t
val shift_area : int -> int -> t -> t

Shift the contents of a UI by a certain amount. Positive values crop the image while negative values pad.

This primitive is used to implement scrolling.

val join_x : t -> t -> t

Horizontally join two images

val join_y : t -> t -> t

Vertically join two images

val join_z : t -> t -> t

Superpose two images. The right one will be on top.

val pack_x : t Lwd_utils.monoid

Horizontal concatenation monoid

val pack_y : t Lwd_utils.monoid

Vertical concatenation monoid

val pack_z : t Lwd_utils.monoid

Superposition monoid

val hcat : t list -> t

Short-hand for horizontally joining a list of images

val vcat : t list -> t

Short-hand for vertically joining a list of images

val zcat : t list -> t

Short-hand for superposing a list of images