Struct easycurses::EasyCurses
source · Expand description
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
, well that’s your own fault.
auto_resize: bool
Determines if the window will automatically resize itself when
KeyResize
comes in through the input channel. Defaults to true. If you
disable this and then don’t call resize yourself then KeyResize
comes
in you’ll have a bad time.
Implementations
sourceimpl EasyCurses
impl EasyCurses
sourcepub fn initialize_system() -> Option<Self>
pub 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 AtomicBool
being flipped on and off. If it is on when you call
this method you get None
back instead.
sourcepub fn set_title_win32(&mut self, title: &str)
pub 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.
sourcepub fn set_cursor_visibility(
&mut self,
vis: CursorVisibility
) -> Option<CursorVisibility>
pub 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
sourcepub fn set_input_mode(&mut self, mode: InputMode) -> bool
pub fn set_input_mode(&mut self, mode: InputMode) -> bool
The terminal gets input from the user. Then it’s sometimes buffered up. At
some point it’s passed into the program’s input buffer, and then
get_input
gets things out of that buffer.
- Character: Input is passed in 1 character at a time, but special characters (such as Ctrl+C and Ctrl+S) are automatically processed for you by the terminal.
- Cooked: Input is passed in 1 line at a time, with the special character processing mentioned above enabled.
- RawCharacter: Input is passed in 1 character at a time, and special character sequences are not processed automatically.
- RawCooked: Input is passed in 1 line at a time, and special character sequences are not processed automatically.
The default mode is inherited from the terminal that started the program (usually Cooked), so you should always set the desired mode explicitly at the start of your program.
See also the Input Mode section of the curses documentation.
sourcepub fn set_input_timeout(&mut self, mode: TimeoutMode)
pub fn set_input_timeout(&mut self, mode: TimeoutMode)
This controls how long get_input
will wait before returning a None
value.
The default mode is an unlimited wait.
The WaitUpTo
value is measured in milliseconds, and any negative value
is treated as 0 (the same as an immediate timeout).
See also: The notimeout curses function.
sourcepub fn set_keypad_enabled(&mut self, use_keypad: bool) -> bool
pub 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
.
sourcepub fn set_echo(&mut self, echoing: bool) -> bool
pub 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.
sourcepub fn is_color_terminal(&self) -> bool
pub fn is_color_terminal(&self) -> bool
Checks if the current terminal supports the use of colors.
sourcepub fn set_color_pair(&mut self, pair: ColorPair)
pub 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.
sourcepub fn set_bold(&mut self, bold_on: bool) -> bool
pub fn set_bold(&mut self, bold_on: bool) -> bool
Enables or disables bold text for all future input.
sourcepub fn set_underline(&mut self, underline_on: bool) -> bool
pub fn set_underline(&mut self, underline_on: bool) -> bool
Enables or disables underlined text for all future input.
sourcepub fn get_row_col_count(&self) -> (i32, i32)
pub fn get_row_col_count(&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);
}
}
sourcepub fn move_rc(&mut self, row: i32, col: i32) -> bool
pub 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.
sourcepub fn get_cursor_rc(&self) -> (i32, i32)
pub fn get_cursor_rc(&self) -> (i32, i32)
Obtains the cursor’s current position using (R,C)
coordinates
relative to the top left corner.
sourcepub fn move_xy(&mut self, x: i32, y: i32) -> bool
pub 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.
sourcepub fn get_cursor_xy(&self) -> (i32, i32)
pub fn get_cursor_xy(&self) -> (i32, i32)
Obtains the cursor’s current position using (X,Y)
coordinates relative
to the bottom left corner.
sourcepub fn set_scrolling(&mut self, scrolling: bool) -> bool
pub 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.
sourcepub fn set_scroll_region(&mut self, top: i32, bottom: i32) -> bool
pub 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
sourcepub fn print<S: AsRef<str>>(&mut self, asref: S) -> bool
pub 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.
sourcepub fn print_char<T: ToChtype>(&mut self, character: T) -> bool
pub fn print_char<T: ToChtype>(&mut self, character: T) -> bool
Prints the given character into the window.
sourcepub fn insert_char<T: ToChtype>(&mut self, character: T) -> bool
pub fn insert_char<T: ToChtype>(&mut self, character: T) -> 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.
sourcepub fn delete_char(&mut self) -> bool
pub 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.
sourcepub fn insert_line(&mut self) -> bool
pub fn insert_line(&mut self) -> bool
Inserts a line above the current line. The bottom line is lost.
sourcepub fn delete_line(&mut self) -> bool
pub 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.
sourcepub fn bulk_insert_delete_line(&mut self, n: i32) -> bool
pub fn bulk_insert_delete_line(&mut self, n: i32) -> bool
For positive n, insert n lines into the specified window above the current line. The n bottom lines are lost. For negative n, delete n lines (starting with the one under the cursor), and move the remaining lines up. The bottom n lines are cleared. The current cursor position remains the same.
sourcepub fn clear(&mut self) -> bool
pub fn clear(&mut self) -> bool
Clears the entire screen.
Note: This function can cause flickering of the output with PDCurses
if you’re clearing the screen and then immediately writing to the whole
screen before you end up calling refresh
. The exact location of the
flickering effect seems to vary from machine to machine. If you intend
to simply replace the whole window with new content, just overwrite the
previous values without calling clear
and things will be fine.
sourcepub fn refresh(&mut self) -> bool
pub 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.
sourcepub fn beep(&mut self)
pub fn beep(&mut self)
Plays an audible beep if possible, if not the screen is flashed. If neither is available then nothing happens.
sourcepub fn flash(&mut self)
pub fn flash(&mut self)
Flashes the screen if possible, if not an audible beep is played. If neither is available then nothing happens.
sourcepub fn get_input(&mut self) -> Option<Input>
pub fn get_input(&mut self) -> Option<Input>
Gets an Input
from the curses input buffer. This will block or not
according to the input mode, see set_input_mode
. If KeyResize
is
seen and auto_resize
is enabled then the window will automatically
update its size for you. In that case, KeyResize
is still passed to
you so that you can change anything else that might need to be updated.
sourcepub fn flush_input(&mut self)
pub fn flush_input(&mut self)
Discards all type-ahead that has been input by the user but not yet read by the program.
sourcepub fn un_get_input(&mut self, input: Input) -> bool
pub 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.
sourcepub fn resize(&mut self, new_lines: i32, new_cols: i32) -> bool
pub fn resize(&mut self, new_lines: i32, new_cols: i32) -> bool
Sets the window to use the number of lines and columns specified. If you
pass zero for both then this will make the window’s data structures
attempt to match the current size of the window. This is done
automatically for you when KeyResize
comes in through the input
buffer.