Module `Nottui.Ui`Source

Sourcetype t

Sourceval pp : Format.formatter -> t -> unit

Printing UI element

Layout specifications

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

Sourceval pp_layout_spec : Format.formatter -> layout_spec -> unit

Printing layout specification

Sourceval layout_spec : t -> layout_spec

Get the layout spec for an UI element

Sourceval layout_width : t -> int

Get the layout width component of an UI element

Sourceval layout_stretch_width : t -> int

Get the layout stretch width strength of an UI element

Sourceval layout_height : t -> int

Get the layout height component of an UI element

Sourceval layout_stretch_height : t -> int

Get the layout height strength of an UI element

Primitive images

Sourceval empty : t

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

Sourceval atom : Notty.image -> t

Primitive surface that displays a Notty image

Sourceval space : int -> int -> t

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

Event handles

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

Source

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.

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

Source

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

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

Sourcetype mouse = Notty.Unescape.mouse

Specification of mouse inputs, taken from Notty

Sourcetype event = [

| `Key of key
| `Mouse of mouse
| `Paste of Notty.Unescape.paste

]

Sourceval mouse_area : mouse_handler -> t -> t

Handle mouse events that happens over an ui.

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

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

Sourceval 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).

Source

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.

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

Sourceval size_sensor : size_sensor -> t -> t

Attach a size sensor to an image

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

Sourceval transient_sensor : frame_sensor -> t -> t

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

Sourceval 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

Source

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.

Source

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

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

Sourceval join_x : t -> t -> t

Horizontally join two images

Sourceval join_y : t -> t -> t

Vertically join two images

Sourceval join_z : t -> t -> t

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

Sourceval pack_x : t Lwd_utils.monoid

Horizontal concatenation monoid

Sourceval pack_y : t Lwd_utils.monoid

Vertical concatenation monoid

Sourceval pack_z : t Lwd_utils.monoid

Superposition monoid

Sourceval hcat : t list -> t

Short-hand for horizontally joining a list of images

Sourceval vcat : t list -> t

Short-hand for vertically joining a list of images

Sourceval zcat : t list -> t

Short-hand for superposing a list of images

package nottui

Module Nottui.UiSource

Layout specifications

Primitive images

Event handles

Sensors

Composite images

Module `Nottui.Ui`Source