Struct EasyCurses

pub struct EasyCurses {
    pub win: Window,
    pub auto_resize: bool,
    /* private fields */
}

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 Option<()> 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 Option<()> 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

impl EasyCurses

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.

Examples found in repository

examples/hello.rs (line 14)

fn main() {
  // Initialize the system
  let mut easy = EasyCurses::initialize_system().unwrap();

  // don't show the cursor
  easy.set_cursor_visibility(CursorVisibility::Invisible);

  // don't echo the user's input
  easy.set_echo(false);

  // we'll print this in green text.
  easy.set_color_pair(colorpair!(Green on Black));

  // Print this string from the current position. The default cursor position
  // is rc(0,0)
  easy.print("Hello world.");

  // Ensure that the user has the latest view of things.
  easy.refresh();

  // Get one input from the user. This is just so that they have a chance to
  // see the message and press a key, otherwise the program would end faster
  // than they could read it.
  easy.get_input();
}

examples/bounds.rs (line 10)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/acs.rs (line 10)

fn main() {
    let mut easy = EasyCurses::initialize_system().unwrap();

    easy.set_echo(false);

    easy.set_color_pair(colorpair!(Green on Black));

    easy.move_rc(0, 0);

    easy.insert_char(acs::llcorner());
    easy.insert_char(acs::lrcorner());
    easy.insert_char(acs::ulcorner());
    easy.insert_char(acs::urcorner());
    easy.insert_char(acs::btee());
    easy.insert_char(acs::hline());
    easy.insert_char(acs::ltee());
    easy.insert_char(acs::plus());
    easy.insert_char(acs::rtee());
    easy.insert_char(acs::ttee());
    easy.insert_char(acs::vline());
    easy.insert_char(acs::s1());
    easy.insert_char(acs::s9());

    easy.move_rc(1, 0);

    easy.insert_char(acs::bullet());
    easy.insert_char(acs::ckboard());
    easy.insert_char(acs::degree());
    easy.insert_char(acs::diamond());
    easy.insert_char(acs::plminus());
    easy.insert_char(acs::block());
    easy.insert_char(acs::board());
    easy.insert_char(acs::darrow());
    easy.insert_char(acs::lantern());
    easy.insert_char(acs::larrow());
    easy.insert_char(acs::rarrow());
    easy.insert_char(acs::uarrow());
    easy.insert_char(acs::s3());

    easy.move_rc(2, 0);

    easy.insert_char(acs::s7());
    easy.insert_char(acs::gequal());
    easy.insert_char(acs::lequal());
    easy.insert_char(acs::nequal());
    easy.insert_char(acs::pi());
    easy.insert_char(acs::sterling());
    easy.insert_char(acs::bbss());
    easy.insert_char(acs::bssb());
    easy.insert_char(acs::sbbs());
    easy.insert_char(acs::sbss());
    easy.insert_char(acs::ssbb());
    easy.insert_char(acs::ssbs());
    easy.insert_char(acs::sssb());
    easy.insert_char(acs::bsbs());
    easy.insert_char(acs::bsss());
    easy.insert_char(acs::sbsb());
    easy.insert_char(acs::ssss());

    easy.refresh();

    easy.get_input();
}

examples/60fps.rs (line 12)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

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.

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

Examples found in repository

examples/hello.rs (line 17)

fn main() {
  // Initialize the system
  let mut easy = EasyCurses::initialize_system().unwrap();

  // don't show the cursor
  easy.set_cursor_visibility(CursorVisibility::Invisible);

  // don't echo the user's input
  easy.set_echo(false);

  // we'll print this in green text.
  easy.set_color_pair(colorpair!(Green on Black));

  // Print this string from the current position. The default cursor position
  // is rc(0,0)
  easy.print("Hello world.");

  // Ensure that the user has the latest view of things.
  easy.refresh();

  // Get one input from the user. This is just so that they have a chance to
  // see the message and press a key, otherwise the program would end faster
  // than they could read it.
  easy.get_input();
}

examples/preserve_panic_message.rs (line 11)

fn main() {
    // We wrap all our use of curses with this function.
    preserve_panic_message(|easy| {
        // In here we get an initialized EasyCurses handle and then proceed to
        // use it exactly like we normally would use it.
        easy.set_cursor_visibility(CursorVisibility::Invisible);
        easy.set_echo(false);
        easy.print("Hello world.");
        easy.refresh();
        easy.get_input();
        panic!("oh no");
    }).unwrap_or_else(|e| match e {
        // This block only runs if there was an error. We might or might not
        // have been able to recover an error message. You technically can pass
        // any value into a panic, but we only get an error message if the panic
        // value was a `String` or `&str`.
        Some(errmsg) => println!("Error Occurred: {}", errmsg),
        None => println!("There was an error, but no error message."),
    });
}

examples/bounds.rs (line 11)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/60fps.rs (line 13)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

pub fn set_input_mode(&mut self, mode: InputMode) -> Option<()>

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.

Examples found in repository

examples/60fps.rs (line 16)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

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.

Examples found in repository

examples/60fps.rs (line 17)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

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

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.

Examples found in repository

examples/bounds.rs (line 13)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/60fps.rs (line 15)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

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

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.

Examples found in repository

examples/hello.rs (line 20)

fn main() {
  // Initialize the system
  let mut easy = EasyCurses::initialize_system().unwrap();

  // don't show the cursor
  easy.set_cursor_visibility(CursorVisibility::Invisible);

  // don't echo the user's input
  easy.set_echo(false);

  // we'll print this in green text.
  easy.set_color_pair(colorpair!(Green on Black));

  // Print this string from the current position. The default cursor position
  // is rc(0,0)
  easy.print("Hello world.");

  // Ensure that the user has the latest view of things.
  easy.refresh();

  // Get one input from the user. This is just so that they have a chance to
  // see the message and press a key, otherwise the program would end faster
  // than they could read it.
  easy.get_input();
}

examples/preserve_panic_message.rs (line 12)

fn main() {
    // We wrap all our use of curses with this function.
    preserve_panic_message(|easy| {
        // In here we get an initialized EasyCurses handle and then proceed to
        // use it exactly like we normally would use it.
        easy.set_cursor_visibility(CursorVisibility::Invisible);
        easy.set_echo(false);
        easy.print("Hello world.");
        easy.refresh();
        easy.get_input();
        panic!("oh no");
    }).unwrap_or_else(|e| match e {
        // This block only runs if there was an error. We might or might not
        // have been able to recover an error message. You technically can pass
        // any value into a panic, but we only get an error message if the panic
        // value was a `String` or `&str`.
        Some(errmsg) => println!("Error Occurred: {}", errmsg),
        None => println!("There was an error, but no error message."),
    });
}

examples/bounds.rs (line 12)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/acs.rs (line 12)

fn main() {
    let mut easy = EasyCurses::initialize_system().unwrap();

    easy.set_echo(false);

    easy.set_color_pair(colorpair!(Green on Black));

    easy.move_rc(0, 0);

    easy.insert_char(acs::llcorner());
    easy.insert_char(acs::lrcorner());
    easy.insert_char(acs::ulcorner());
    easy.insert_char(acs::urcorner());
    easy.insert_char(acs::btee());
    easy.insert_char(acs::hline());
    easy.insert_char(acs::ltee());
    easy.insert_char(acs::plus());
    easy.insert_char(acs::rtee());
    easy.insert_char(acs::ttee());
    easy.insert_char(acs::vline());
    easy.insert_char(acs::s1());
    easy.insert_char(acs::s9());

    easy.move_rc(1, 0);

    easy.insert_char(acs::bullet());
    easy.insert_char(acs::ckboard());
    easy.insert_char(acs::degree());
    easy.insert_char(acs::diamond());
    easy.insert_char(acs::plminus());
    easy.insert_char(acs::block());
    easy.insert_char(acs::board());
    easy.insert_char(acs::darrow());
    easy.insert_char(acs::lantern());
    easy.insert_char(acs::larrow());
    easy.insert_char(acs::rarrow());
    easy.insert_char(acs::uarrow());
    easy.insert_char(acs::s3());

    easy.move_rc(2, 0);

    easy.insert_char(acs::s7());
    easy.insert_char(acs::gequal());
    easy.insert_char(acs::lequal());
    easy.insert_char(acs::nequal());
    easy.insert_char(acs::pi());
    easy.insert_char(acs::sterling());
    easy.insert_char(acs::bbss());
    easy.insert_char(acs::bssb());
    easy.insert_char(acs::sbbs());
    easy.insert_char(acs::sbss());
    easy.insert_char(acs::ssbb());
    easy.insert_char(acs::ssbs());
    easy.insert_char(acs::sssb());
    easy.insert_char(acs::bsbs());
    easy.insert_char(acs::bsss());
    easy.insert_char(acs::sbsb());
    easy.insert_char(acs::ssss());

    easy.refresh();

    easy.get_input();
}

examples/60fps.rs (line 14)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

pub fn is_color_terminal(&self) -> bool

Checks if the current terminal supports the use of colors.

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.

Examples found in repository

examples/hello.rs (line 23)

fn main() {
  // Initialize the system
  let mut easy = EasyCurses::initialize_system().unwrap();

  // don't show the cursor
  easy.set_cursor_visibility(CursorVisibility::Invisible);

  // don't echo the user's input
  easy.set_echo(false);

  // we'll print this in green text.
  easy.set_color_pair(colorpair!(Green on Black));

  // Print this string from the current position. The default cursor position
  // is rc(0,0)
  easy.print("Hello world.");

  // Ensure that the user has the latest view of things.
  easy.refresh();

  // Get one input from the user. This is just so that they have a chance to
  // see the message and press a key, otherwise the program would end faster
  // than they could read it.
  easy.get_input();
}

examples/acs.rs (line 14)

fn main() {
    let mut easy = EasyCurses::initialize_system().unwrap();

    easy.set_echo(false);

    easy.set_color_pair(colorpair!(Green on Black));

    easy.move_rc(0, 0);

    easy.insert_char(acs::llcorner());
    easy.insert_char(acs::lrcorner());
    easy.insert_char(acs::ulcorner());
    easy.insert_char(acs::urcorner());
    easy.insert_char(acs::btee());
    easy.insert_char(acs::hline());
    easy.insert_char(acs::ltee());
    easy.insert_char(acs::plus());
    easy.insert_char(acs::rtee());
    easy.insert_char(acs::ttee());
    easy.insert_char(acs::vline());
    easy.insert_char(acs::s1());
    easy.insert_char(acs::s9());

    easy.move_rc(1, 0);

    easy.insert_char(acs::bullet());
    easy.insert_char(acs::ckboard());
    easy.insert_char(acs::degree());
    easy.insert_char(acs::diamond());
    easy.insert_char(acs::plminus());
    easy.insert_char(acs::block());
    easy.insert_char(acs::board());
    easy.insert_char(acs::darrow());
    easy.insert_char(acs::lantern());
    easy.insert_char(acs::larrow());
    easy.insert_char(acs::rarrow());
    easy.insert_char(acs::uarrow());
    easy.insert_char(acs::s3());

    easy.move_rc(2, 0);

    easy.insert_char(acs::s7());
    easy.insert_char(acs::gequal());
    easy.insert_char(acs::lequal());
    easy.insert_char(acs::nequal());
    easy.insert_char(acs::pi());
    easy.insert_char(acs::sterling());
    easy.insert_char(acs::bbss());
    easy.insert_char(acs::bssb());
    easy.insert_char(acs::sbbs());
    easy.insert_char(acs::sbss());
    easy.insert_char(acs::ssbb());
    easy.insert_char(acs::ssbs());
    easy.insert_char(acs::sssb());
    easy.insert_char(acs::bsbs());
    easy.insert_char(acs::bsss());
    easy.insert_char(acs::sbsb());
    easy.insert_char(acs::ssss());

    easy.refresh();

    easy.get_input();
}

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

Enables or disables bold text for all future input.

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

Enables or disables underlined text for all future input.

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);
    }
}

Examples found in repository

examples/bounds.rs (line 16)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/60fps.rs (line 21)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

pub fn move_rc(&mut self, row: i32, col: i32) -> Option<()>

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.

Examples found in repository

examples/bounds.rs (line 19)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/acs.rs (line 16)

fn main() {
    let mut easy = EasyCurses::initialize_system().unwrap();

    easy.set_echo(false);

    easy.set_color_pair(colorpair!(Green on Black));

    easy.move_rc(0, 0);

    easy.insert_char(acs::llcorner());
    easy.insert_char(acs::lrcorner());
    easy.insert_char(acs::ulcorner());
    easy.insert_char(acs::urcorner());
    easy.insert_char(acs::btee());
    easy.insert_char(acs::hline());
    easy.insert_char(acs::ltee());
    easy.insert_char(acs::plus());
    easy.insert_char(acs::rtee());
    easy.insert_char(acs::ttee());
    easy.insert_char(acs::vline());
    easy.insert_char(acs::s1());
    easy.insert_char(acs::s9());

    easy.move_rc(1, 0);

    easy.insert_char(acs::bullet());
    easy.insert_char(acs::ckboard());
    easy.insert_char(acs::degree());
    easy.insert_char(acs::diamond());
    easy.insert_char(acs::plminus());
    easy.insert_char(acs::block());
    easy.insert_char(acs::board());
    easy.insert_char(acs::darrow());
    easy.insert_char(acs::lantern());
    easy.insert_char(acs::larrow());
    easy.insert_char(acs::rarrow());
    easy.insert_char(acs::uarrow());
    easy.insert_char(acs::s3());

    easy.move_rc(2, 0);

    easy.insert_char(acs::s7());
    easy.insert_char(acs::gequal());
    easy.insert_char(acs::lequal());
    easy.insert_char(acs::nequal());
    easy.insert_char(acs::pi());
    easy.insert_char(acs::sterling());
    easy.insert_char(acs::bbss());
    easy.insert_char(acs::bssb());
    easy.insert_char(acs::sbbs());
    easy.insert_char(acs::sbss());
    easy.insert_char(acs::ssbb());
    easy.insert_char(acs::ssbs());
    easy.insert_char(acs::sssb());
    easy.insert_char(acs::bsbs());
    easy.insert_char(acs::bsss());
    easy.insert_char(acs::sbsb());
    easy.insert_char(acs::ssss());

    easy.refresh();

    easy.get_input();
}

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

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

Examples found in repository

examples/bounds.rs (line 20)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

pub fn move_xy(&mut self, x: i32, y: i32) -> Option<()>

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.

Examples found in repository

examples/bounds.rs (line 24)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

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

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

Examples found in repository

examples/bounds.rs (line 25)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

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

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.

Examples found in repository

examples/60fps.rs (line 18)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

pub fn set_scroll_region(&mut self, top: i32, bottom: i32) -> Option<()>

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

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

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.

Examples found in repository

examples/hello.rs (line 27)

fn main() {
  // Initialize the system
  let mut easy = EasyCurses::initialize_system().unwrap();

  // don't show the cursor
  easy.set_cursor_visibility(CursorVisibility::Invisible);

  // don't echo the user's input
  easy.set_echo(false);

  // we'll print this in green text.
  easy.set_color_pair(colorpair!(Green on Black));

  // Print this string from the current position. The default cursor position
  // is rc(0,0)
  easy.print("Hello world.");

  // Ensure that the user has the latest view of things.
  easy.refresh();

  // Get one input from the user. This is just so that they have a chance to
  // see the message and press a key, otherwise the program would end faster
  // than they could read it.
  easy.get_input();
}

examples/preserve_panic_message.rs (line 13)

fn main() {
    // We wrap all our use of curses with this function.
    preserve_panic_message(|easy| {
        // In here we get an initialized EasyCurses handle and then proceed to
        // use it exactly like we normally would use it.
        easy.set_cursor_visibility(CursorVisibility::Invisible);
        easy.set_echo(false);
        easy.print("Hello world.");
        easy.refresh();
        easy.get_input();
        panic!("oh no");
    }).unwrap_or_else(|e| match e {
        // This block only runs if there was an error. We might or might not
        // have been able to recover an error message. You technically can pass
        // any value into a panic, but we only get an error message if the panic
        // value was a `String` or `&str`.
        Some(errmsg) => println!("Error Occurred: {}", errmsg),
        None => println!("There was an error, but no error message."),
    });
}

examples/bounds.rs (line 21)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/60fps.rs (line 57)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

pub fn print_char<T: ToChtype>(&mut self, character: T) -> Option<()>

Prints the given character into the window.

Examples found in repository

examples/bounds.rs (line 30)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

pub fn insert_char<T: ToChtype>(&mut self, character: T) -> Option<()>

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.

Examples found in repository

examples/acs.rs (line 18)

fn main() {
    let mut easy = EasyCurses::initialize_system().unwrap();

    easy.set_echo(false);

    easy.set_color_pair(colorpair!(Green on Black));

    easy.move_rc(0, 0);

    easy.insert_char(acs::llcorner());
    easy.insert_char(acs::lrcorner());
    easy.insert_char(acs::ulcorner());
    easy.insert_char(acs::urcorner());
    easy.insert_char(acs::btee());
    easy.insert_char(acs::hline());
    easy.insert_char(acs::ltee());
    easy.insert_char(acs::plus());
    easy.insert_char(acs::rtee());
    easy.insert_char(acs::ttee());
    easy.insert_char(acs::vline());
    easy.insert_char(acs::s1());
    easy.insert_char(acs::s9());

    easy.move_rc(1, 0);

    easy.insert_char(acs::bullet());
    easy.insert_char(acs::ckboard());
    easy.insert_char(acs::degree());
    easy.insert_char(acs::diamond());
    easy.insert_char(acs::plminus());
    easy.insert_char(acs::block());
    easy.insert_char(acs::board());
    easy.insert_char(acs::darrow());
    easy.insert_char(acs::lantern());
    easy.insert_char(acs::larrow());
    easy.insert_char(acs::rarrow());
    easy.insert_char(acs::uarrow());
    easy.insert_char(acs::s3());

    easy.move_rc(2, 0);

    easy.insert_char(acs::s7());
    easy.insert_char(acs::gequal());
    easy.insert_char(acs::lequal());
    easy.insert_char(acs::nequal());
    easy.insert_char(acs::pi());
    easy.insert_char(acs::sterling());
    easy.insert_char(acs::bbss());
    easy.insert_char(acs::bssb());
    easy.insert_char(acs::sbbs());
    easy.insert_char(acs::sbss());
    easy.insert_char(acs::ssbb());
    easy.insert_char(acs::ssbs());
    easy.insert_char(acs::sssb());
    easy.insert_char(acs::bsbs());
    easy.insert_char(acs::bsss());
    easy.insert_char(acs::sbsb());
    easy.insert_char(acs::ssss());

    easy.refresh();

    easy.get_input();
}

pub fn delete_char(&mut self) -> Option<()>

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.

pub fn insert_line(&mut self) -> Option<()>

Inserts a line above the current line. The bottom line is lost.

pub fn delete_line(&mut self) -> Option<()>

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.

pub fn bulk_insert_delete_line(&mut self, n: i32) -> Option<()>

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.

pub fn clear(&mut self) -> Option<()>

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.

pub fn refresh(&mut self) -> Option<()>

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.

Examples found in repository

examples/hello.rs (line 30)

fn main() {
  // Initialize the system
  let mut easy = EasyCurses::initialize_system().unwrap();

  // don't show the cursor
  easy.set_cursor_visibility(CursorVisibility::Invisible);

  // don't echo the user's input
  easy.set_echo(false);

  // we'll print this in green text.
  easy.set_color_pair(colorpair!(Green on Black));

  // Print this string from the current position. The default cursor position
  // is rc(0,0)
  easy.print("Hello world.");

  // Ensure that the user has the latest view of things.
  easy.refresh();

  // Get one input from the user. This is just so that they have a chance to
  // see the message and press a key, otherwise the program would end faster
  // than they could read it.
  easy.get_input();
}

examples/preserve_panic_message.rs (line 14)

fn main() {
    // We wrap all our use of curses with this function.
    preserve_panic_message(|easy| {
        // In here we get an initialized EasyCurses handle and then proceed to
        // use it exactly like we normally would use it.
        easy.set_cursor_visibility(CursorVisibility::Invisible);
        easy.set_echo(false);
        easy.print("Hello world.");
        easy.refresh();
        easy.get_input();
        panic!("oh no");
    }).unwrap_or_else(|e| match e {
        // This block only runs if there was an error. We might or might not
        // have been able to recover an error message. You technically can pass
        // any value into a panic, but we only get an error message if the panic
        // value was a `String` or `&str`.
        Some(errmsg) => println!("Error Occurred: {}", errmsg),
        None => println!("There was an error, but no error message."),
    });
}

examples/bounds.rs (line 42)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/acs.rs (line 68)

fn main() {
    let mut easy = EasyCurses::initialize_system().unwrap();

    easy.set_echo(false);

    easy.set_color_pair(colorpair!(Green on Black));

    easy.move_rc(0, 0);

    easy.insert_char(acs::llcorner());
    easy.insert_char(acs::lrcorner());
    easy.insert_char(acs::ulcorner());
    easy.insert_char(acs::urcorner());
    easy.insert_char(acs::btee());
    easy.insert_char(acs::hline());
    easy.insert_char(acs::ltee());
    easy.insert_char(acs::plus());
    easy.insert_char(acs::rtee());
    easy.insert_char(acs::ttee());
    easy.insert_char(acs::vline());
    easy.insert_char(acs::s1());
    easy.insert_char(acs::s9());

    easy.move_rc(1, 0);

    easy.insert_char(acs::bullet());
    easy.insert_char(acs::ckboard());
    easy.insert_char(acs::degree());
    easy.insert_char(acs::diamond());
    easy.insert_char(acs::plminus());
    easy.insert_char(acs::block());
    easy.insert_char(acs::board());
    easy.insert_char(acs::darrow());
    easy.insert_char(acs::lantern());
    easy.insert_char(acs::larrow());
    easy.insert_char(acs::rarrow());
    easy.insert_char(acs::uarrow());
    easy.insert_char(acs::s3());

    easy.move_rc(2, 0);

    easy.insert_char(acs::s7());
    easy.insert_char(acs::gequal());
    easy.insert_char(acs::lequal());
    easy.insert_char(acs::nequal());
    easy.insert_char(acs::pi());
    easy.insert_char(acs::sterling());
    easy.insert_char(acs::bbss());
    easy.insert_char(acs::bssb());
    easy.insert_char(acs::sbbs());
    easy.insert_char(acs::sbss());
    easy.insert_char(acs::ssbb());
    easy.insert_char(acs::ssbs());
    easy.insert_char(acs::sssb());
    easy.insert_char(acs::bsbs());
    easy.insert_char(acs::bsss());
    easy.insert_char(acs::sbsb());
    easy.insert_char(acs::ssss());

    easy.refresh();

    easy.get_input();
}

examples/60fps.rs (line 59)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

pub fn beep(&mut self)

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

pub fn flash(&mut self)

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

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.

Examples found in repository

examples/hello.rs (line 35)

fn main() {
  // Initialize the system
  let mut easy = EasyCurses::initialize_system().unwrap();

  // don't show the cursor
  easy.set_cursor_visibility(CursorVisibility::Invisible);

  // don't echo the user's input
  easy.set_echo(false);

  // we'll print this in green text.
  easy.set_color_pair(colorpair!(Green on Black));

  // Print this string from the current position. The default cursor position
  // is rc(0,0)
  easy.print("Hello world.");

  // Ensure that the user has the latest view of things.
  easy.refresh();

  // Get one input from the user. This is just so that they have a chance to
  // see the message and press a key, otherwise the program would end faster
  // than they could read it.
  easy.get_input();
}

examples/preserve_panic_message.rs (line 15)

fn main() {
    // We wrap all our use of curses with this function.
    preserve_panic_message(|easy| {
        // In here we get an initialized EasyCurses handle and then proceed to
        // use it exactly like we normally would use it.
        easy.set_cursor_visibility(CursorVisibility::Invisible);
        easy.set_echo(false);
        easy.print("Hello world.");
        easy.refresh();
        easy.get_input();
        panic!("oh no");
    }).unwrap_or_else(|e| match e {
        // This block only runs if there was an error. We might or might not
        // have been able to recover an error message. You technically can pass
        // any value into a panic, but we only get an error message if the panic
        // value was a `String` or `&str`.
        Some(errmsg) => println!("Error Occurred: {}", errmsg),
        None => println!("There was an error, but no error message."),
    });
}

examples/bounds.rs (line 47)

fn main() {
    // Common startup
    let mut easy = EasyCurses::initialize_system().unwrap();
    easy.set_cursor_visibility(CursorVisibility::Invisible);
    easy.set_echo(false);
    easy.set_keypad_enabled(true);

    // Check the size of the window.
    let (row_count, col_count) = easy.get_row_col_count();

    // A message using RC coordinates.
    easy.move_rc(0, 0);
    assert_eq!(easy.get_cursor_rc(), (0, 0));
    easy.print("Hello from RC 0,0.");

    // A message using XY coordinates.
    easy.move_xy(1, 1);
    assert_eq!(easy.get_cursor_xy(), (1, 1));
    easy.print("Hello from XY 1,1.");

    // Upper right corner has a '+'
    easy.move_rc(0, col_count - 1);
    easy.print_char('+');

    // Lower left corner has a '-', note that the col_count based argument is
    // the first argument now because we're using the xy coordinate system.
    easy.move_xy(col_count - 1, 0);
    easy.print_char('-');

    // Middle of the screen (ish) has a '*'
    easy.move_xy(col_count / 2, row_count / 2);
    easy.print_char('*');

    // Ensure that the user has the latest view of things.
    easy.refresh();

    // Get one input from the user. This is just so that they have a chance to
    // see the message and press a key, otherwise the program would end faster
    // than they could read it.
    easy.get_input();
}

examples/acs.rs (line 70)

fn main() {
    let mut easy = EasyCurses::initialize_system().unwrap();

    easy.set_echo(false);

    easy.set_color_pair(colorpair!(Green on Black));

    easy.move_rc(0, 0);

    easy.insert_char(acs::llcorner());
    easy.insert_char(acs::lrcorner());
    easy.insert_char(acs::ulcorner());
    easy.insert_char(acs::urcorner());
    easy.insert_char(acs::btee());
    easy.insert_char(acs::hline());
    easy.insert_char(acs::ltee());
    easy.insert_char(acs::plus());
    easy.insert_char(acs::rtee());
    easy.insert_char(acs::ttee());
    easy.insert_char(acs::vline());
    easy.insert_char(acs::s1());
    easy.insert_char(acs::s9());

    easy.move_rc(1, 0);

    easy.insert_char(acs::bullet());
    easy.insert_char(acs::ckboard());
    easy.insert_char(acs::degree());
    easy.insert_char(acs::diamond());
    easy.insert_char(acs::plminus());
    easy.insert_char(acs::block());
    easy.insert_char(acs::board());
    easy.insert_char(acs::darrow());
    easy.insert_char(acs::lantern());
    easy.insert_char(acs::larrow());
    easy.insert_char(acs::rarrow());
    easy.insert_char(acs::uarrow());
    easy.insert_char(acs::s3());

    easy.move_rc(2, 0);

    easy.insert_char(acs::s7());
    easy.insert_char(acs::gequal());
    easy.insert_char(acs::lequal());
    easy.insert_char(acs::nequal());
    easy.insert_char(acs::pi());
    easy.insert_char(acs::sterling());
    easy.insert_char(acs::bbss());
    easy.insert_char(acs::bssb());
    easy.insert_char(acs::sbbs());
    easy.insert_char(acs::sbss());
    easy.insert_char(acs::ssbb());
    easy.insert_char(acs::ssbs());
    easy.insert_char(acs::sssb());
    easy.insert_char(acs::bsbs());
    easy.insert_char(acs::bsss());
    easy.insert_char(acs::sbsb());
    easy.insert_char(acs::ssss());

    easy.refresh();

    easy.get_input();
}

examples/60fps.rs (line 33)

fn main() {
  // Normal setup
  let mut easy = EasyCurses::initialize_system().unwrap();
  easy.set_cursor_visibility(CursorVisibility::Invisible);
  easy.set_echo(false);
  easy.set_keypad_enabled(true);
  easy.set_input_mode(InputMode::Character);
  easy.set_input_timeout(TimeoutMode::Immediate);
  easy.set_scrolling(true);

  // We need to know how wide our screen is.
  let (_, mut col_count) = easy.get_row_col_count();

  // Sadly we can't make this const since it has to unwrap and all that, but
  // ideally this could be a const. You could use lazy_static I guess if you
  // really cared, but it's not a huge deal.
  let frame_target_duration = Duration::new(1, 0).checked_div(60).expect("failed when rhs!=0, what?");

  // We start at an arbitrary position.
  let mut position = 5;
  loop {
    let top_of_loop = Instant::now();
    // Gather/process any pending input
    while let Some(input) = easy.get_input() {
      match input {
        Input::KeyLeft => position = max(0, position - 1),
        Input::KeyRight => position = min(col_count - 1, position + 1),
        Input::KeyResize => {
          col_count = easy.get_row_col_count().1;
          position = min(col_count - 1, position);
        }
        other => println!("Unknown: {:?}", other),
      }
    }
    // Compute what we'll display.
    let output = repeat('#').take(position as usize).collect::<String>();

    // Sleep a bit if we need to. This actually sleeps a little longer than
    // just the right time because it doesn't account for the display time
    // we'll use up after the sleep happens. However, curses doesn't really
    // demand perfect animation anyway.
    let elapsed_this_frame = top_of_loop.elapsed();
    if let Some(frame_remaining) = frame_target_duration.checked_sub(elapsed_this_frame) {
      sleep(frame_remaining);
    }

    // Display
    easy.print("\n");
    easy.print(&output);
    easy.refresh();
  }
}

pub fn flush_input(&mut self)

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

pub fn un_get_input(&mut self, input: Input) -> Option<()>

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.

pub fn resize(&mut self, new_lines: i32, new_cols: i32) -> Option<()>

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.

Trait Implementations

impl Debug for EasyCurses

fn fmt(&self, f: &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.