README.md
1# pancurses [](https://travis-ci.org/ihalila/pancurses) [](https://ci.appveyor.com/project/ihalila/pancurses) [](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
){kind=link}
){kind=link}