#raw-pointers #tui #ncurses #api-bindings #mouse-event

ncursesw-win

An extension wrapper around the ncursesw-rs crate that encapsulates the exposed raw pointers of the core NCurses TUI library

15 releases

0.6.3 Feb 22, 2022
0.6.2 Jan 6, 2022
0.4.0 Dec 9, 2019
0.3.1 Nov 7, 2019
0.1.4 Jul 13, 2019

#314 in Command-line interface

MIT license

505KB
6.5K SLoC

ncursesw-win Crates.io Build Status MIT licensed Lines of Code

This crate is a wrapper around the ncursesw crate, it's purpose is too abstracts away the raw pointers that NCurses uses and function in a safe way, however a knowledge of how NCurses works is advised to use the true power of this library.

Please see the README.md for ncursesw for more details.

Inclusion

[dependencies]
ncursesw-win = "0.6"

Or to use the latest git version

[dependencies]
ncursesw-win = { git = "https://github.com/narfit66/ncursesw-win-rs" }

Building

The compiled library will be built in the target directory.

cargo build

For additional information on how to custom compile please see the Building, Custom Build and Features sections in the ncursesw README.md crate.

How to Use

extern crate ncurseswwin;

use ncurseswwin::*;

To use attributes and color pairs

use ncurseswwin::normal::*; // for 'ansi' color pairs and attributes...
use ncurseswwin::extend::*; // or for 'extended' color pairs and attributes.

To use menus

use ncurseswwin::menu::*;

To use forms

use ncurseswwin::form::*;

Instead of calling initscr() and endwin() to initialise and teardown the NCurses library (these can still be called as the ncursesw crate is public) use the ncursesw_entry() function. This initialises and tears down NCurses and provided the ability to catch panics in a controlled maner by passing them back to the client code as the error type NCurseswWinError::Panic { message }.

To create a window use Window::new() which will teardown correctly when going out of scope and provides all NCurses functionality associatiated with a NCurses window. Likewise a pad is created using Pad::new() and a panel using Panel::new().

All NCurses methods associated with a Window, Pad or RipoffWindow use either their original NCurses name or where specifically passed the pointer to the structure _win_st the 'w' has been removed, for example the NCurses 'C' function wget_wch(WINDOW*) has become the method self.get_wch() (where self is an instance of a Window for example).

All NCurses methods associated with a Screen use either the original NCurses name or where specifically passed the pointer to the structure screen the _sp suffix has been removed, for example the NCurses 'C' function start_color_sp(SCREEN*) has become the method self.start_color() (where self is an instance of a Screen for example). To create a window or pad associated with a screen use Window::new_sp() or Pad::new_sp() respecitivly.

The NCurses ripoff and mouse features are encapsulated, please see example code for how to use these features.

Examples

Examples are built by cargo build --examples. To run them, use cargo run --example <EXAMPLE>.

Current examples are Safe Initialisation/Calling Of NCurses (ncursesw_entry-test), Ansi Border Drawing (border-test), Unicode Border Drawing (border_set-test), Unicode Box Drawing (box_drawing-test), Mouse Events (mouse-test), Ripoff Lines (ripoffline-test), Non-Blocking Get (getch_nonblocking-test), Screen (screen-test), Window (window-test) and Menu (menu-test).

Documentation

Documentation for this crate can be found here.

License

Licensed under the MIT license, see LICENSE

Dependencies

~1.7–4.5MB
~83K SLoC