Struct easycurses::EasyCurses

pub struct EasyCurses {
    pub win: Window,
    // some fields omitted
}

This is a handle to all your fun curses functionality.

EasyCurses will automatically restore the terminal when you drop it, so you don't need to worry about any manual cleanup. Automatic cleanup will happen even if your program panics and unwinds, but it will not happen if your program panics and aborts (obviously). So, don't abort the program while curses is active, or your terminal session will just be ruined.

Except in the case of is_color_terminal, all EasyCurses methods that return a bool use it to indicate if the requested operation was successful or not. Unfortunately, the curses library doesn't provide any more info than that, so a bool is all you get.

Fields

win: Window

This is the inner pancurses Window that the EasyCurses type wraps over.

This is only intended to be used as a last resort, if you really want to call something that's not here. Under normal circumstances you shouldn't need to touch this field at all. It's not "unsafe" to use in the rust/memory sense, but if you access this field and then cause a bug in EasyCurses, that's your fault.

Methods

impl EasyCurses

fn initialize_system() -> Option<Self>

Initializes the curses system so that you can begin using curses.

The name is long to remind you of the seriousness of attempting to turn on curses: If the C layer encounters an error while trying to initialize the user's terminal into curses mode it will "helpfully" print an error message and exit the process on its own. There's no way to prevent this from happening at the Rust level.

If the terminal supports colors, they are automatically activated and ColorPair values are initialized for all color foreground and background combinations.

Errors

Curses must not be double-initialized. This is tracked by easycurses with an atomic bool being flipped on and off. If the bool is on when you call this method you get None back instead.

fn set_title_win32(&mut self, title: &str)

On Win32 systems this allows you to set the title of the PDcurses window. On other systems this does nothing at all.

fn set_cursor_visibility(
    &mut self,
    vis: CursorVisibility
) -> Option<CursorVisibility>

Attempts to assign a new cursor visibility. If this is successful you get a Some back with the old setting inside. If this fails you get a None back. For more info see curs_set

fn set_character_break(&mut self, cbreak: bool) -> bool

In character break mode (cbreak), characters typed by the user are made available immediately, and erase/kill/backspace character processing is not performed. When this mode is off (nocbreak) user input is not available to the application until a newline has been typed. The default mode is not specified (but happens to often be cbreak).

See also the Input Mode section of the curses documentation.

fn set_keypad_enabled(&mut self, use_keypad: bool) -> bool

Enables special key processing from buttons such as the keypad and arrow keys. This defaults to false. You probably want to set it to true. If it's not on and the user presses a special key then get_key will return will do nothing or give ERR.

fn set_echo(&mut self, echoing: bool) -> bool

Enables or disables the automatic echoing of input into the window as the user types. Default to on, but you probably want it to be off most of the time.

fn is_color_terminal(&self) -> bool

Checks if the current terminal supports the use of colors.

fn set_color_pair(&mut self, pair: ColorPair)

Sets the current color pair of the window. Output at any location will use this pair until a new pair is set. Does nothing if the terminal does not support colors in the first place.

fn set_bold(&mut self, bold_on: bool) -> bool

Enables or disables bold text for all future input.

fn set_underline(&mut self, underline_on: bool) -> bool

Enables or disables unerlined text for all future input.

fn get_row_col_count(&mut self) -> (i32, i32)

Returns the number of rows and columns available in the window. Each of these are the number of locations in that dimension, but the rows and cols (as well as the Xs and Ys if you care to use that coordinate space) use 0-based indexing, so the actual addressable locations are numbered 0 to N-1, similar to with slices, .len(), and indexing. Fortunately, the normal rust Range type already handles this for us. If you wanted to iterate every cell of the window you'd probably use a loop like this:

let mut easy = easycurses::EasyCurses::initialize_system().unwrap();
let (row_count,col_count) = easy.get_row_col_count();
// using RC coordinates.
for row in 0..row_count {
    for col in 0..col_count {
        easy.move_rc(row,col);
        let (actual_row,actual_col) = easy.get_cursor_rc();
        assert!(actual_row == row && actual_col == col);
    }
}
// using XY coordinates.
for y in 0..row_count {
    for x in 0..col_count {
        easy.move_xy(x,y);
        let (actual_x,actual_y) = easy.get_cursor_xy();
        assert!(actual_x == x && actual_y == y);
    }
}

fn move_rc(&mut self, row: i32, col: i32) -> bool

Moves the virtual cursor to the row and column specified, relative to the top left ("notepad" space). Does not move the terminal's displayed cursor (if any) until refresh is also called. Out of bounds locations cause this command to be ignored.

fn get_cursor_rc(&self) -> (i32, i32)

Obtains the cursor's current position using (R,C) coordinates relative to the top left corner.

fn move_xy(&mut self, x: i32, y: i32) -> bool

Moves the virtual cursor to the x and y specified, relative to the bottom left ("cartesian" space). Does not move the terminal's displayed cursor (if any) until refresh is also called. Out of bounds locations cause this command to be ignored.

fn get_cursor_xy(&self) -> (i32, i32)

Obtains the cursor's current position using (X,Y) coordinates relative to the bottom left corner.

fn set_scrolling(&mut self, scrolling: bool) -> bool

When scrolling is enabled, any attempt to move off the bottom margin will cause lines within the scrolling region to scroll up one line. If a scrolling region is set but scrolling is not enabled then attempts to go off the bottom will just print nothing instead. Use set_scroll_region to control the size of the scrolling region.

fn set_scroll_region(&mut self, top: i32, bottom: i32) -> bool

Sets the top and bottom margins of the scrolling region. The inputs should be the line numbers (relative to the top of the screen) for the borders. Either border can be 0.

See also: setscrreg

fn print<S: AsRef<str>>(&mut self, asref: S) -> bool

Prints the given string-like value into the window by printing each individual character into the window. If there is any error encountered upon printing a character, that cancels the printing of the rest of the characters.

fn print_char(&mut self, character: char) -> bool

Prints the given character into the window.

fn insert_char(&mut self, character: char) -> bool

Inserts the character desired at the current location, pushing the current character at that location (and all after it on the same line) one cell to the right.

fn delete_char(&mut self) -> bool

Deletes the character under the cursor. Characters after it on same the line are pulled left one position and the final character cell is left blank. The cursor position does not move.

fn delete_line(&mut self) -> bool

Deletes the line under the cursor. Lines below are moved up one line and the final line is left blank. The cursor position does not move.

fn clear(&mut self) -> bool

Clears the entire screen.

fn refresh(&mut self) -> bool

Refreshes the window's appearance on the screen. With some implementations you don't need to call this, the screen will refresh itself on its own. However, for portability, you should call this at the end of each draw cycle.

fn beep(&mut self)

Plays an audible beep if possible, if not the screen is flashed. If neither is available then nothing happens.

fn flash(&mut self)

Flashes the screen if possible, if not an audible beep is played. If neither is available then nothing happens.

fn set_input_mode(&mut self, mode: InputMode)

This controls if get_input is blocking or not. The default mode is Blocking.

See also: The notimeout curses function.

fn get_input(&mut self) -> Option<Input>

Gets an Input from the curses input buffer. Depending on the timeout setting that y

fn flush_input(&mut self)

Discards all type-ahead that has been input by the user but not yet read by the program.

fn un_get_input(&mut self, input: &Input) -> bool

Pushes an Input value into the input stack so that it will be returned by the next call to get_input. The return value is if the operation was successful.

Trait Implementations

impl Debug for EasyCurses

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Drop for EasyCurses

fn drop(&mut self)

Dropping EasyCurses causes the endwin curses function to be called.