1# pancurses [![Build Status](https://travis-ci.org/ihalila/pancurses.svg?branch=master)](https://travis-ci.org/ihalila/pancurses) [![Build status](https://ci.appveyor.com/api/projects/status/x4j52ihig9n2e25y?svg=true)](https://ci.appveyor.com/project/ihalila/pancurses) [![Crates.io](https://img.shields.io/crates/v/pancurses.svg)](https://crates.io/crates/pancurses) 2 3pancurses is a curses library for Rust that supports both Linux and Windows 4by abstracting away the backend that it uses 5([ncurses-rs](https://github.com/jeaye/ncurses-rs) and 6[pdcurses-sys](https://github.com/ihalila/pdcurses-sys) respectively). 7 8The aim is to provide a more Rustic interface over the usual curses functions 9for ease of use while remaining close enough to curses to make porting easy. 10 11## [Documentation](https://docs.rs/pancurses) 12 13## Requirements 14#### Linux 15ncurses-rs links with the native ncurses library so that needs to be installed 16so that the linker can find it. 17 18Check [ncurses-rs](https://github.com/jeaye/ncurses-rs) for more details. 19 20#### Windows 21pdcurses-sys compiles the native PDCurses library as part of the build process, 22so you need to have a compatible C compiler available that matches the ABI of 23the version of Rust you're using (so either gcc for the GNU ABI or cl for MSVC) 24 25Check [pdcurses-sys](https://github.com/ihalila/pdcurses-sys) for more details. 26 27## Usage 28Cargo.toml 29```toml 30[dependencies] 31pancurses = "0.16" 32``` 33 34main.rs 35```rust 36extern crate pancurses; 37 38use pancurses::{initscr, endwin}; 39 40fn main() { 41 let window = initscr(); 42 window.printw("Hello Rust"); 43 window.refresh(); 44 window.getch(); 45 endwin(); 46} 47``` 48 49## Pattern matching with getch() 50 51```rust 52extern crate pancurses; 53 54use pancurses::{initscr, endwin, Input, noecho}; 55 56fn main() { 57 let window = initscr(); 58 window.printw("Type things, press delete to quit\n"); 59 window.refresh(); 60 window.keypad(true); 61 noecho(); 62 loop { 63 match window.getch() { 64 Some(Input::Character(c)) => { window.addch(c); }, 65 Some(Input::KeyDC) => break, 66 Some(input) => { window.addstr(&format!("{:?}", input)); }, 67 None => () 68 } 69 } 70 endwin(); 71} 72``` 73 74## Handling mouse input 75 76To receive mouse events you need to both enable keypad mode and set a mouse mask that corresponds 77to the events you are interested in. Mouse events are received in the same way as keyboard events, 78ie. by calling getch(). 79 80```rust 81extern crate pancurses; 82 83use pancurses::{ALL_MOUSE_EVENTS, endwin, getmouse, initscr, mousemask, Input}; 84 85fn main() { 86 let window = initscr(); 87 88 window.keypad(true); // Set keypad mode 89 mousemask(ALL_MOUSE_EVENTS, std::ptr::null_mut()); // Listen to all mouse events 90 91 window.printw("Click in the terminal, press q to exit\n"); 92 window.refresh(); 93 94 loop { 95 match window.getch() { 96 Some(Input::KeyMouse) => { 97 if let Ok(mouse_event) = getmouse() { 98 window.mvprintw(1, 0, 99 &format!("Mouse at {},{}", mouse_event.x, mouse_event.y), 100 ); 101 }; 102 } 103 Some(Input::Character(x)) if x == 'q' => break, 104 _ => (), 105 } 106 } 107 endwin(); 108} 109``` 110 111You can also receive events for the mouse simply moving (as long as the terminal you're running on 112supports it) by also specifying the REPORT_MOUSE_POSITION flag: 113```rust 114mousemask(ALL_MOUSE_EVENTS | REPORT_MOUSE_POSITION, std::ptr::null_mut()); 115``` 116 117## Terminal resizing 118 119Whenever the terminal is resized by the user a Input::KeyResize event is raised. You should handle 120this by calling ```resize_term(0, 0)``` to have curses adjust it's internal structures to match the 121new size. 122 123## PDCurses (Windows) details 124 125pdcurses-sys supports two flavors of PDCurses, win32a and win32. win32a is the GDI mode while win32 126runs in the Windows console. win32a has better support for colors and text effects. 127 128By default the win32a flavor is used, but you can specify which one you want to use by using Cargo 129flags. Simply specify the feature in Cargo.toml like so: 130 131```rust 132[dependencies.pancurses] 133version = "0.16" 134features = ["win32a"] 135``` 136or 137 138```rust 139[dependencies.pancurses] 140version = "0.16" 141features = ["win32"] 142``` 143 144### (Font, Paste) menu 145 146PDCurses win32a has a menu that allows you to change the font and paste text into the window. 147pancurses disables the window by default, though the user can still right-click the title bar to 148access it. If you want to retain the PDCurses default behaviour of having the menu there set the 149feature ```"show_menu"```. 150 151### Resizing 152 153On win32a the default is to allow the user to freely resize the window. If you wish to disable 154resizing set the feature ```"disable_resize"``` 155 156## License 157 158Licensed under the MIT license, see [LICENSE.md](LICENSE.md) 159