Up  Next

Module Newt


module Newt: sig .. end
Interface to the newt text window system.

The newt windowing system is a terminal-based window and widget library designed for writing applications with a simple, but user-friendly, interface. While newt is not intended to provide the rich feature set advanced applications may require, it has proven to be flexible enough for a wide range of applications (most notably, Red Hat's installation process).

Notes

There is not a large amount of documentation for newt. The best documentation is probably Eric Troan's newt tutorial.

OCaml functions are derived using a predictable naming scheme. So for example the C function newtPopWindow becomes Newt.pop_window.

There are plenty of OCaml examples in the examples/ subdirectory.

Safety

The OCaml bindings attempt to be as type and memory safe as possible. However newt itself makes this difficult. Newt code has many arbitrary limits, no checks on memory allocation, and inherent confusion about types.

Do not use functions from the unsafe Newt_int (internal) module unless you know what you're doing.

Exceptions


exception NewtFailure of string

Types


type color_set = Newt_int.newtColorSet 
type colors = Newt_int.newtColors 
type flags_sense = Newt_int.newtFlagsSense

type flag =
| RETURNEXIT
| HIDDEN
| SCROLL
| DISABLED
| BORDER
| WRAP
| NOF12
| MULTIPLE
| SELECTED
| CHECKBOX
| PASSWORD
| SHOWCURSOR

type fd_flag =
| FD_READ
| FD_WRITE
| FD_EXCEPT

Functions


val init : unit -> unit
val finished : unit -> unit
val init_and_finish : (unit -> 'a) -> 'a
init_and_finish f calls Newt.init, then runs the function f (), then finishes (cleans up) the terminal.

It does the right thing even if f throws an exception.

val cls : unit -> unit
val resize_screen : int -> unit
val wait_for_key : unit -> unit
val clear_key_buffer : unit -> unit
val delay : int -> unit
val open_window : int -> int -> int -> int -> string -> unit
val centered_window : int -> int -> string -> unit
val pop_window : unit -> unit
val pop_window_no_refresh : unit -> unit
val set_colors : Newt_int.newtColors -> unit
val set_color : Newt_int.newtColorSet -> string -> string -> unit
val refresh : unit -> unit
val suspend : unit -> unit
val resume : unit -> int
val push_help_line : string -> unit
val redraw_help_line : unit -> unit
val pop_help_line : unit -> unit
val draw_root_text : int -> int -> string -> unit
val bell : unit -> unit
val cursor_on : unit -> unit
val cursor_off : unit -> unit
val get_screen_size : unit -> int * int

Components

We use phantom types here to add some type safety around components. All components have a type of at least [> `Component] component. Specific types of components have an extra variant indicating the type and limiting what functions you can safely call. Thus for example buttons have type [`Button|`Component] component.

A component_ptr is a special type of component that may only be compared against other components, but not used in any way. It is returned by certain functions that get the "current" subcomponent from a form or component.

type 'a component = Newt._component 
type _component 
type component_ptr 
val component_equals : component_ptr -> [> `Component ] component -> bool

Buttons


val compact_button : int -> int -> string -> [ `Button | `Component ] component
val button : int -> int -> string -> [ `Button | `Component ] component

Checkboxes, radio buttons


val checkbox : int ->
       int ->
       string -> char -> string option -> [ `Checkbox | `Component ] component
val checkbox_get_value : [> `Checkbox ] component -> char
val checkbox_set_value : [> `Checkbox ] component -> char -> unit
val checkbox_set_flags : [> `Checkbox ] component ->
       flag list -> Newt_int.newtFlagsSense -> unit
val radio_button : int ->
       int ->
       string ->
       bool ->
       [> `Radio ] component option -> [ `Component | `Radio ] component
val radio_get_current : [> `Radio ] component -> component_ptr

Labels


val label : int -> int -> string -> [ `Component | `Label ] component
val label_set_text : [> `Label ] component -> string -> unit

Scrollbars


val vertical_scrollbar : int ->
       int ->
       int ->
       color_set ->
       color_set -> [ `Component | `VerticalScrollbar ] component
val scrollbar_set : [> `VerticalScrollbar ] component -> int -> int -> unit

Listboxes

Newt lets you store arbitrary data for each row in a listbox. We can't let you do that, but instead we let you store values of a single type in the listbox (if you really want to store arbitrary values, use a variant).

The newt documentation confuses the terms 'key' and 'data' as if they refer to something different. In fact they are the same thing and we refer to it as 'data' everywhere.

type 'a listbox 
val listbox : int -> int -> int -> flag list -> 'a listbox
Create a listbox.
val listbox_get_current : 'a listbox -> 'a option
This returns the data field from the current item, for listboxes which only allow single selection.

If nothing is selected, None is returned.

val listbox_set_current : 'a listbox -> int -> unit
Set the current selection for listboxes which allow single selection.
val listbox_set_current_by_key : 'a listbox -> 'a -> unit
Set the current selection to the row containing data.
Raises Not_found if data is not found.
val listbox_set_entry : 'a listbox -> int -> string -> unit
val listbox_set_width : 'a listbox -> int -> unit
val listbox_set_data : 'a listbox -> int -> 'a -> unit
val listbox_append_entry : 'a listbox -> string -> 'a -> unit
listbox_append_entry lb text data appends a new listbox entry consisting of the text string text and data data to the end of the listbox.
val listbox_insert_entry : 'a listbox -> string -> 'a -> 'a option -> unit
listbox_insert_entry lb text data after inserts a new listbox entry consisting of the text string text and data data after the current listbox entry with data field after. It returns the position of the new entry.
Raises Not_found if after is not found.
val listbox_delete_entry : 'a listbox -> 'a -> unit
listbox_delete_entry lb data deletes the listbox entry which contains data.
Raises Not_found if data is not found.
val listbox_clear : 'a listbox -> unit
Remove all listbox entries.
val listbox_get_entry : 'a listbox -> int -> string * 'a
Return a member of the listbox.
val listbox_get_selection : 'a listbox -> 'a array
listbox_get_selection lb return an array of data from the items selected.
val listbox_clear_selection : 'a listbox -> unit
Clear the current selection.
val listbox_select_item : 'a listbox -> 'a -> flags_sense -> unit
Select the item containing data.
Raises Not_found if data is not found.
val listbox_item_count : 'a listbox -> int
Return the total number of items in the listbox.
val component_of_listbox : 'a listbox -> [ `Component | `Listbox ] component
Convert the specialised listbox type back to a normal component, eg. allowing it to be added to forms.

Checkbox trees



Textboxes


val textbox_reflowed : int ->
       int ->
       string ->
       int ->
       int -> int -> flag list -> [ `Component | `Textbox ] component
val textbox : int ->
       int ->
       int -> int -> flag list -> [ `Component | `Textbox ] component
val textbox_set_text : [> `Textbox ] component -> string -> unit
val textbox_set_height : [> `Textbox ] component -> int -> unit
val textbox_get_num_lines : [> `Textbox ] component -> int
val reflow_text : string -> int -> int -> int -> string * int * int

Entries


val entry : int ->
       int ->
       string option ->
       int -> flag list -> [ `Component | `Entry ] component
val entry_set : [> `Entry ] component -> string -> bool -> unit
val entry_get_value : [> `Entry ] component -> string
val entry_set_flags : [> `Entry ] component -> flag list -> flags_sense -> unit

Scales


val scale : int -> int -> int -> int64 -> [ `Component | `Scale ] component
val scale_set : [> `Scale ] component -> int64 -> unit

Forms


val form : [> `VerticalScrollbar ] component option ->
       string option -> flag list -> [ `Component | `Form ] component
val form_set_timer : [> `Form ] component -> int -> unit
val form_watch_fd : [> `Form ] component -> Unix.file_descr -> fd_flag list -> unit
val form_set_size : [> `Form ] component -> unit
val form_get_current : [> `Form ] component -> component_ptr
val form_set_background : [> `Form ] component -> int -> unit
val form_set_current : [> `Form ] component -> [> `Component ] component -> unit
val form_add_component : [> `Form ] component -> [> `Component ] component -> unit
val form_add_components : [> `Form ] component -> [> `Component ] component list -> unit
val form_set_height : [> `Form ] component -> int -> unit
val form_set_width : [> `Form ] component -> int -> unit
val run_form : [> `Form ] component -> component_ptr option
val form_run : [> `Form ] component -> Newt_int.newtExitStruct
val form_add_hot_key : [> `Form ] component -> int -> unit

Generic component functions


val component_takes_focus : [> `Component ] component -> bool -> unit
component_takes_focus co bool enables or disables a component.
val component_add_callback : [> `Component ] component -> (unit -> unit) -> unit
component_add_callback co f adds a general callback function f to a component. This is only available for certain types of component -- see the Newt documentation for more information.

Keys