From 38a22537d9ec509252e47314ede03d1eabb3d4e9 Mon Sep 17 00:00:00 2001 From: Timon Date: Tue, 17 Sep 2019 10:50:39 +0200 Subject: [PATCH] Examples cleanup (#225) --- crossterm_cursor/README.md | 2 +- crossterm_cursor/examples/cc_cursor.rs | 144 ------- crossterm_input/README.md | 2 +- crossterm_input/examples/ci_input.rs | 26 -- crossterm_input/examples/ci_key_events.rs | 133 ------ crossterm_input/src/input/input.rs | 2 +- crossterm_screen/README.md | 4 +- .../examples/cs_alternate_screen.rs | 10 - crossterm_screen/examples/cs_raw_mode.rs | 12 - crossterm_style/README.md | 2 +- crossterm_style/examples/cs_style.rs | 391 ------------------ crossterm_terminal/README.md | 4 +- crossterm_terminal/examples/ct_terminal.rs | 131 ------ crossterm_winapi/README.md | 2 +- docs/CHANGELOG.md | 6 +- docs/Contributing.md | 12 +- docs/mdbook/src/SUMMARY.md | 6 +- docs/mdbook/src/input.md | 2 +- docs/mdbook/src/styling.md | 2 +- examples/README.md | 36 +- examples/alternate_screen.rs | 1 + examples/command.rs | 1 + examples/command_bar.rs | 1 + examples/crossterm.rs | 1 + examples/cursor.rs | 1 + examples/key_events.rs | 5 +- examples/raw_mode.rs | 1 + examples/style.rs | 1 + examples/terminal.rs | 1 + 29 files changed, 62 insertions(+), 880 deletions(-) delete mode 100644 crossterm_cursor/examples/cc_cursor.rs delete mode 100644 crossterm_input/examples/ci_input.rs delete mode 100644 crossterm_input/examples/ci_key_events.rs delete mode 100644 crossterm_screen/examples/cs_alternate_screen.rs delete mode 100644 crossterm_screen/examples/cs_raw_mode.rs delete mode 100644 crossterm_style/examples/cs_style.rs delete mode 100644 crossterm_terminal/examples/ct_terminal.rs diff --git a/crossterm_cursor/README.md b/crossterm_cursor/README.md index 06f4247..3db833a 100644 --- a/crossterm_cursor/README.md +++ b/crossterm_cursor/README.md @@ -79,7 +79,7 @@ My first recommendation is to use the [command API](https://timonpost.github.io/ Because it is more convenient, faster, and easier to use. ## Examples -The [examples](./examples) folder has more complete and verbose examples. +The [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folder has more complete and verbose examples. ```rust use crossterm_cursor::cursor; diff --git a/crossterm_cursor/examples/cc_cursor.rs b/crossterm_cursor/examples/cc_cursor.rs deleted file mode 100644 index ebf02f3..0000000 --- a/crossterm_cursor/examples/cc_cursor.rs +++ /dev/null @@ -1,144 +0,0 @@ -//! -//! Examples of actions that could be performed with the cursor. -//! -#![allow(unused_must_use, dead_code)] - -use std::io::Write; -use std::time::Instant; - -use crossterm_cursor::{cursor, queue, Goto, Hide, Output, QueueableCommand}; - -/// Set the cursor to position X: 10, Y: 5 in the terminal. -fn goto() { - // Get the cursor - let cursor = cursor(); - // Set the cursor to position X: 10, Y: 5 in the terminal - cursor.goto(10, 5); -} - -/// get the cursor position -fn pos() { - // Get the cursor - let cursor = cursor(); - // get the cursor position. - let (x, y) = cursor.pos(); - - println!("{} {}", x, y); -} - -/// Move the cursor 3 up | demonstration. -fn move_up() { - // Get the cursor - let mut cursor = cursor(); - - // Move the cursor to position 3 times to the up in the terminal - cursor.move_up(10); -} - -/// Move the cursor 3 to the right | demonstration. -fn move_right() { - let mut cursor = cursor(); - // Move the cursor to position 3 times to the right in the terminal - cursor.move_right(3); -} - -/// Move the cursor 3 down | demonstration. -fn move_down() { - let mut cursor = cursor(); - // Move the cursor to position 3 times to the down in the terminal - cursor.move_down(3); -} - -/// Save and reset cursor position | demonstration.. -fn save_and_reset_position() { - let cursor = cursor(); - - // Goto X: 5 Y: 5 - cursor.goto(5, 5); - // Safe cursor position: X: 5 Y: 5 - cursor.save_position(); - // Goto X: 5 Y: 20 - cursor.goto(5, 20); - // Print at X: 5 Y: 20. - println!("Yea!"); - // Reset back to X: 5 Y: 5. - cursor.reset_position(); - // Print Back at X: 5 Y: 5. - println!("Back"); - - println!() -} - -/// Hide cursor display | demonstration. -fn hide_cursor() { - let cursor = cursor(); - cursor.hide(); -} - -/// Show cursor display | demonstration. -fn show_cursor() { - let cursor = cursor(); - cursor.show(); -} - -/// Show cursor display, only works on certain terminals.| demonstration -fn blink_cursor() { - let cursor = cursor(); - cursor.blink(false); - cursor.blink(false); -} - -fn benchmark_cursor_goto() -> f32 { - let mut stdout = ::std::io::stdout(); - - let instant1 = Instant::now(); - for _ in 0..10 { - for x in 0..200 { - for y in 0..50 { - queue!(stdout, Goto(x, y), Hide, Output(y.to_string())); - } - } - } - - let new_api = instant1.elapsed(); - let cursor = cursor(); - let instant2 = Instant::now(); - for _ in 0..10 { - for x in 0..200 { - for y in 0..50 { - cursor.goto(x, y); - print!("{}", y.to_string()); - } - } - } - let old_api = instant2.elapsed(); - - let speed_improvement = ((old_api.as_millis() as f32 - new_api.as_millis() as f32) - / old_api.as_millis() as f32) - * 100.; - - speed_improvement -} - -fn start_goto_benchmark() { - let mut performance_metrics = Vec::new(); - for _ in 1..=20 { - performance_metrics.push(benchmark_cursor_goto()); - } - - println!( - "Average Performance Improvement mesearued 10 times {:.2} %", - performance_metrics.iter().sum::() / 20. - ); -} - -fn main() { - let stdout = ::std::io::stdout(); - - stdout - .queue(Goto(5, 5)) - .queue(Output("#".to_string())) - .flush(); - - println!("out: {}", Output("1".to_string())); -} diff --git a/crossterm_input/README.md b/crossterm_input/README.md index 6049fee..6077102 100644 --- a/crossterm_input/README.md +++ b/crossterm_input/README.md @@ -77,7 +77,7 @@ These are the features of this crate: - RawScreen (from `crossterm_screen`) ## Examples -The [examples](./examples) folder has more complete and verbose examples. +The [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folder has more complete and verbose examples. _Simple Readings_ ```rust diff --git a/crossterm_input/examples/ci_input.rs b/crossterm_input/examples/ci_input.rs deleted file mode 100644 index a3c035a..0000000 --- a/crossterm_input/examples/ci_input.rs +++ /dev/null @@ -1,26 +0,0 @@ -use crossterm_input::input; - -fn read_char() { - let input = input(); - - match input.read_char() { - Ok(s) => println!("char typed: {}", s), - Err(e) => println!("char error : {}", e), - } -} - -fn read_line() { - let input = input(); - - match input.read_line() { - Ok(s) => println!("string typed: {}", s), - Err(e) => println!("error: {}", e), - } -} - -fn main() { - // un-comment below and run with - // `cargo run --example input`: - read_char(); - read_line(); -} diff --git a/crossterm_input/examples/ci_key_events.rs b/crossterm_input/examples/ci_key_events.rs deleted file mode 100644 index 0f0ab3c..0000000 --- a/crossterm_input/examples/ci_key_events.rs +++ /dev/null @@ -1,133 +0,0 @@ -#![allow(dead_code)] - -use std::{thread, time::Duration}; - -use crossterm_input::{input, InputEvent, KeyEvent, MouseButton, MouseEvent, RawScreen}; - -fn process_input_event(key_event: InputEvent) -> bool { - match key_event { - InputEvent::Keyboard(k) => { - match k { - KeyEvent::Char(c) => match c { - 'q' => { - println!("The 'q' key is hit and the program is not listening to input anymore.\n\n"); - return true; - } - _ => { - println!("{}", format!("'{}' pressed\n\n", c)); - } - }, - KeyEvent::Alt(c) => { - println!("{}", format!("ALT +'{}' pressed\n\n", c)); - } - KeyEvent::Ctrl(c) => { - println!("{}", format!("CTRL +'{}' Pressed\n\n", c)); - } - KeyEvent::Esc => { - println!("{}", format!("ESC pressed\n\n")); - } - KeyEvent::F(number) => { - println!("{}", format!("F{} key pressed\n\n", number)); - } - KeyEvent::PageUp => { - println!("{}", format!("Page Up\n\n")); - } - KeyEvent::PageDown => { - println!("{}", format!("Page Down\n\n")); - } - KeyEvent::Delete => { - println!("{}", format!("Delete\n\n")); - } - _ => { - println!("{}", format!("OTHER: {:?}\n\n", k)); - () - } - } - } - InputEvent::Mouse(m) => match m { - MouseEvent::Press(b, x, y) => match b { - MouseButton::Left => { - println!("{}", format!("left mouse press @ {}, {}\n\n", x, y)); - } - MouseButton::Right => { - println!("{}", format!("right mouse press @ {}, {}\n\n", x, y)); - } - MouseButton::Middle => { - println!("{}", format!("mid mouse press @ {}, {}\n\n", x, y)); - } - MouseButton::WheelUp => println!("{}", format!("wheel up @ {}, {}\n\n", x, y)), - MouseButton::WheelDown => { - println!("{}", format!("wheel down @ {}, {}\n\n", x, y)); - } - }, - MouseEvent::Release(x, y) => { - println!("{}", format!("mouse released @ {}, {}\n\n", x, y)); - } - MouseEvent::Hold(x, y) => { - println!("{}", format!("dragging @ {}, {}\n\n", x, y)); - } - _ => { - println!("{}", "Unknown mouse event"); - } - }, - _ => println!("Unknown!"), - } - - return false; -} - -fn read_asynchronously() { - // make sure to enable raw mode, this will make sure key events won't be handled by the terminal it's self and allows crossterm to read the input and pass it back to you. - if let Ok(_raw) = RawScreen::into_raw_mode() { - let input = input(); - - // enable mouse events to be captured. - input.enable_mouse_mode().unwrap(); - - let mut stdin = input.read_async(); - - loop { - if let Some(key_event) = stdin.next() { - if process_input_event(key_event) { - break; - } - } - thread::sleep(Duration::from_millis(50)); - } - - // disable mouse events to be captured. - input.disable_mouse_mode().unwrap(); - } // <=== raw modes will be disabled here -} // <=== background reader will be disposed when dropped. - -fn read_synchronously() { - // make sure to enable raw mode, this will make sure key events won't be handled by the terminal it's self and allows crossterm to read the input and pass it back to you. - if let Ok(_raw) = RawScreen::into_raw_mode() { - let input = input(); - - // enable mouse events to be captured. - input.enable_mouse_mode().unwrap(); - - let mut sync_stdin = input.read_sync(); - - loop { - let event = sync_stdin.next(); - - if let Some(key_event) = event { - if process_input_event(key_event) { - break; - } - } - } - - // disable mouse events to be captured. - input.disable_mouse_mode().unwrap(); - } // <=== raw modes will be disabled here -} - -fn main() { - // un-comment below and run with - // `cargo run --example key_events`: - read_synchronously(); - // read_asynchronously(); -} diff --git a/crossterm_input/src/input/input.rs b/crossterm_input/src/input/input.rs index 89870d9..9fd59fc 100644 --- a/crossterm_input/src/input/input.rs +++ b/crossterm_input/src/input/input.rs @@ -99,7 +99,7 @@ impl TerminalInput { self.input.read_async() } - /// Read the input asynchronously until a certain character is hit, which means that input events are gathered on the background and will be queued for you to read. + /// Read the input asynchronously until a certain delimiter (character as byte) is hit, which means that input events are gathered on the background and will be queued for you to read. /// /// If you want a blocking or less resource consuming read to happen, use `read_sync()`. This will leave alone the background thread and queues and will be a blocking read. /// diff --git a/crossterm_screen/README.md b/crossterm_screen/README.md index 6b462d9..ad5df4a 100644 --- a/crossterm_screen/README.md +++ b/crossterm_screen/README.md @@ -44,7 +44,7 @@ In case you are wondering what 'alternate' or 'raw' screen is, you could checkou ## Getting Started This documentation is only for `crossterm_screen` version `0.2`. -Also, check out the [examples](./examples) folders with detailed examples for all functionality of this crate +Also, check out the [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folders with detailed examples for all functionality of this crate and the [book](https://timonpost.github.io/crossterm/docs/screen.html) for more information about how to use the alternate or raw screen options. Add the `crossterm_screen` package to your `Cargo.toml` file. @@ -81,7 +81,7 @@ Planned features: - make is possible to switch between multiple buffers. ## Examples -The [examples](./examples) folder has more complete and verbose examples. +The [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folder has more complete and verbose examples. ## Tested terminals - Windows Powershell diff --git a/crossterm_screen/examples/cs_alternate_screen.rs b/crossterm_screen/examples/cs_alternate_screen.rs deleted file mode 100644 index 38a0e92..0000000 --- a/crossterm_screen/examples/cs_alternate_screen.rs +++ /dev/null @@ -1,10 +0,0 @@ -use crossterm_screen::AlternateScreen; - -/// print wait screen on alternate screen, then switch back. -#[allow(unused_variables)] -fn main() { - // move to the alternate screen, 'false' determines if the alternate screen should be in raw mode. - if let Ok(alternate) = AlternateScreen::to_alternate(false) { - // do some stuff on the alternate screen. - } // <- alternate screen will be disabled when dropped. -} diff --git a/crossterm_screen/examples/cs_raw_mode.rs b/crossterm_screen/examples/cs_raw_mode.rs deleted file mode 100644 index 6790d1e..0000000 --- a/crossterm_screen/examples/cs_raw_mode.rs +++ /dev/null @@ -1,12 +0,0 @@ -use std::io::stdout; - -use crossterm_screen::{IntoRawMode, RawScreen}; - -#[allow(unused_variables)] -fn main() { - // create a Screen instance that operates on the default output: io::stdout(). By passing in 'true', we make this screen 'raw' - let screen = RawScreen::into_raw_mode(); - let screen = stdout().into_raw_mode(); - - // raw screen will be disabled when it goes out of scope. -} diff --git a/crossterm_style/README.md b/crossterm_style/README.md index 8479700..a6aa8e0 100644 --- a/crossterm_style/README.md +++ b/crossterm_style/README.md @@ -78,7 +78,7 @@ These are the features of this crate: - Text Attributes: bold, italic, underscore and crossed word and [more](https://timonpost.github.io/crossterm/docs/styling.html#attributes) (Windows 10 and UNIX only) ## Examples -The [examples](./examples) folder has more complete and verbose examples. +The [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folder has more complete and verbose examples. _style text with attributes_ ```rust diff --git a/crossterm_style/examples/cs_style.rs b/crossterm_style/examples/cs_style.rs deleted file mode 100644 index bdd5fa4..0000000 --- a/crossterm_style/examples/cs_style.rs +++ /dev/null @@ -1,391 +0,0 @@ -//! -//! Examples of coloring the terminal. -//! -use crossterm_style::{color, Attribute, Color, Colored, Colorize, Styler}; - -/// print some red text | demonstration. -pub fn paint_foreground() { - println!("{}", "Red foreground text: {}".red()); - println!("{} Red foreground text", Colored::Fg(Color::Red)); -} - -/// print some text on red background | demonstration. -pub fn paint_background() { - println!("{}", "Red background text: {}".on_red()); - println!("{} Red background text", Colored::Bg(Color::Red)); -} - -/// Print all available foreground colors | demonstration. -pub fn print_all_foreground_colors_with_enum() { - // we use `Reset` to restore the foreground back to normal at the end of the line. - println!( - "Black : \t\t {} ■ {}\n", - Colored::Fg(Color::Black), - Attribute::Reset - ); - println!( - "Red : \t\t {} ■ {}\n", - Colored::Fg(Color::Red), - Attribute::Reset - ); - println!( - "DarkRed : \t\t {} ■ {}\n", - Colored::Fg(Color::DarkRed), - Attribute::Reset - ); - println!( - "Cyan : \t\t {} ■ {}\n", - Colored::Fg(Color::Cyan), - Attribute::Reset - ); - println!( - "DarkCyan : \t\t {} ■ {}\n", - Colored::Fg(Color::DarkCyan), - Attribute::Reset - ); - println!( - "Green : \t\t {} ■ {}\n", - Colored::Fg(Color::Green), - Attribute::Reset - ); - println!( - "DarkGreen : \t\t {} ■ {}\n", - Colored::Fg(Color::DarkGreen), - Attribute::Reset - ); - println!( - "Blue : \t\t {} ■ {}\n", - Colored::Fg(Color::Blue), - Attribute::Reset - ); - println!( - "DarkBlue : \t\t {} ■ {}\n", - Colored::Fg(Color::DarkBlue), - Attribute::Reset - ); - println!( - "Magenta : \t\t {} ■ {}\n", - Colored::Fg(Color::Magenta), - Attribute::Reset - ); - println!( - "DarkMagenta : \t\t{} ■ {}\n", - Colored::Fg(Color::DarkMagenta), - Attribute::Reset - ); - println!( - "Yellow : \t\t {} ■ {}\n", - Colored::Fg(Color::Yellow), - Attribute::Reset - ); - println!( - "DarkYellow : \t\t {} ■ {}\n", - Colored::Fg(Color::DarkYellow), - Attribute::Reset - ); - println!( - "Grey : \t\t {} ■ {}\n", - Colored::Fg(Color::Grey), - Attribute::Reset - ); - println!( - "White : \t\t {} ■ {}\n", - Colored::Fg(Color::White), - Attribute::Reset - ); - - // custom rgb value (Windows 10 and UNIX systems) - println!( - "{} some colored text", - Colored::Fg(Color::Rgb { - r: 10, - g: 10, - b: 10 - }) - ); - - // custom ansi color value (Windows 10 and UNIX systems) - println!("{} some colored text", Colored::Fg(Color::AnsiValue(10))); -} - -/// Print all available foreground colors | demonstration. -pub fn print_all_foreground_colors_with_method() { - println!( - "Black : \t\t {} {}\n", - "■".black(), - Attribute::Reset - ); - println!("Red : \t\t {} {}\n", "■".red(), Attribute::Reset); - println!( - "DarkRed : \t\t {} {}\n", - "■".dark_red(), - Attribute::Reset - ); - println!("Cyan : \t\t {} {}\n", "■".cyan(), Attribute::Reset); - println!( - "DarkCyan : \t\t {} {}\n", - "■".dark_cyan(), - Attribute::Reset - ); - println!( - "Green : \t\t {} {}\n", - "■".green(), - Attribute::Reset - ); - println!( - "DarkGreen : \t\t {} {}\n", - "■".dark_green(), - Attribute::Reset - ); - println!("Blue : \t\t {} {}\n", "■".blue(), Attribute::Reset); - println!( - "DarkBlue : \t\t {} {}\n", - "■".dark_blue(), - Attribute::Reset - ); - println!( - "Magenta : \t\t {} {}\n", - "■".magenta(), - Attribute::Reset - ); - println!( - "DarkMagenta : \t\t {} {}\n", - "■".dark_magenta(), - Attribute::Reset - ); - println!( - "Yellow : \t\t {} {}\n", - "■".yellow(), - Attribute::Reset - ); - println!( - "DarkYellow : \t\t {} {}\n", - "■".dark_yellow(), - Attribute::Reset - ); - println!("Grey : \t\t {} {}\n", "■".grey(), Attribute::Reset); - println!( - "White : \t\t {} {}\n", - "■".white(), - Attribute::Reset - ); -} - -/// Print all available foreground colors | demonstration. -pub fn print_all_background_colors_with_enum() { - println!( - "Black : \t\t {} ■ {}\n", - Colored::Bg(Color::Black), - Attribute::Reset - ); - println!( - "Red : \t\t {} ■ {}\n", - Colored::Bg(Color::Red), - Attribute::Reset - ); - println!( - "DarkRed : \t\t {} ■ {}\n", - Colored::Bg(Color::DarkRed), - Attribute::Reset - ); - println!( - "Cyan : \t\t {} ■ {}\n", - Colored::Bg(Color::Cyan), - Attribute::Reset - ); - println!( - "DarkCyan : \t\t {} ■ {}\n", - Colored::Bg(Color::DarkCyan), - Attribute::Reset - ); - println!( - "Green : \t\t {} ■ {}\n", - Colored::Bg(Color::Green), - Attribute::Reset - ); - println!( - "DarkGreen : \t\t {} ■ {}\n", - Colored::Bg(Color::DarkGreen), - Attribute::Reset - ); - println!( - "Blue : \t\t {} ■ {}\n", - Colored::Bg(Color::Blue), - Attribute::Reset - ); - println!( - "DarkBlue : \t\t {} ■ {}\n", - Colored::Bg(Color::DarkBlue), - Attribute::Reset - ); - println!( - "Magenta : \t\t {} ■ {}\n", - Colored::Bg(Color::Magenta), - Attribute::Reset - ); - println!( - "DarkMagenta : \t\t{} ■ {}\n", - Colored::Bg(Color::DarkMagenta), - Attribute::Reset - ); - println!( - "Yellow : \t\t {} ■ {}\n", - Colored::Bg(Color::Yellow), - Attribute::Reset - ); - println!( - "DarkYellow : \t\t {} ■ {}\n", - Colored::Bg(Color::DarkYellow), - Attribute::Reset - ); - println!( - "Grey : \t\t {} ■ {}\n", - Colored::Bg(Color::Grey), - Attribute::Reset - ); - println!( - "White : \t\t {} ■ {}\n", - Colored::Bg(Color::White), - Attribute::Reset - ); - - // custom rgb value (Windows 10 and UNIX systems) - println!( - "{} some colored text", - Colored::Bg(Color::Rgb { - r: 80, - g: 10, - b: 10 - }) - ); - - // custom ansi color value (Windows 10 and UNIX systems) - println!("{} some colored text", Colored::Bg(Color::AnsiValue(10))); -} - -/// Print all available foreground colors | demonstration. -pub fn print_all_background_colors_with_method() { - println!( - "Black : \t\t {} {}\n", - "■".on_black(), - Attribute::Reset - ); - println!( - "Red : \t\t {} {}\n", - "■".on_red(), - Attribute::Reset - ); - println!( - "DarkRed : \t\t {} {}\n", - "■".on_dark_red(), - Attribute::Reset - ); - println!( - "Cyan : \t\t {} {}\n", - "■".on_cyan(), - Attribute::Reset - ); - println!( - "DarkCyan : \t\t {} {}\n", - "■".on_dark_cyan(), - Attribute::Reset - ); - println!( - "Green : \t\t {} {}\n", - "■".on_green(), - Attribute::Reset - ); - println!( - "DarkGreen : \t\t {} {}\n", - "■".on_dark_green(), - Attribute::Reset - ); - println!( - "Blue : \t\t {} {}\n", - "■".on_blue(), - Attribute::Reset - ); - println!( - "DarkBlue : \t\t {} {}\n", - "■".on_dark_blue(), - Attribute::Reset - ); - println!( - "Magenta : \t\t {} {}\n", - "■".on_magenta(), - Attribute::Reset - ); - println!( - "DarkMagenta : \t\t {} {}\n", - "■".on_dark_magenta(), - Attribute::Reset - ); - println!( - "Yellow : \t\t {} {}\n", - "■".on_yellow(), - Attribute::Reset - ); - println!( - "DarkYellow : \t\t {} {}\n", - "■".on_dark_yellow(), - Attribute::Reset - ); - println!( - "Grey : \t\t {} {}\n", - "■".on_grey(), - Attribute::Reset - ); - println!( - "White : \t\t {} {}\n", - "■".on_white(), - Attribute::Reset - ); -} - -/// Print text with all available attributes. Note that this can only be used at unix systems and that some are not supported widely | demonstration.. -#[cfg(unix)] -pub fn print_text_with_attributes() { - println!("{}", "Normal text"); - println!("{}", "Bold text".bold()); - println!("{}", "Italic text".italic()); - println!("{}", "Slow blinking text".slow_blink()); - println!("{}", "Rapid blinking text".rapid_blink()); - println!("{}", "Hidden text".hidden()); - println!("{}", "Underlined text".underlined()); - println!("{}", "Reversed text".reverse()); - println!("{}", "Dim text".dim()); - println!("{}", "Crossed out text".crossed_out()); - // ... - - println!( - "{} Underlined {} No Underline", - Attribute::Underlined, - Attribute::NoUnderline - ); - // ... -} - -// Print text with all available attributes. Note that this can only be used at unix systems and that some are not supported widely | demonstration.. -#[cfg(windows)] -pub fn print_text_with_attributes() { - println!("{}", "Normal text"); - println!("{}", "Bold text".bold()); - println!("{}", "Underlined text".underlined()); - println!("{}", "Negative text".negative()); -} - -/// Print all supported RGB colors, not supported for Windows systems < 10 | demonstration. -pub fn print_supported_colors() { - let count = color().get_available_color_count().unwrap(); - - for i in 0..count { - println!("Test {}", Colored::Bg(Color::AnsiValue(i as u8))); - } -} - -pub fn reset_fg_and_bg() { - println!("{}", Colored::Fg(Color::Reset)); - println!("{}", Colored::Bg(Color::Reset)); -} - -fn main() {} diff --git a/crossterm_terminal/README.md b/crossterm_terminal/README.md index 6955743..b92aa76 100644 --- a/crossterm_terminal/README.md +++ b/crossterm_terminal/README.md @@ -41,7 +41,7 @@ When you want to use other modules as well you might want to use crossterm with ## Getting Started -This documentation is only for `crossterm_terminal` version `0.2` check the [examples](./examples) folders with detailed examples for all functionality of this crate. +This documentation is only for `crossterm_terminal` version `0.2` check the [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folders with detailed examples for all functionality of this crate. Add the `crossterm_terminal` package to your `Cargo.toml` file. @@ -82,7 +82,7 @@ Because it is more convenient, faster, and easier to use. ## Examples -The [examples](./examples) folder has more complete and verbose examples. +The [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folder has more complete and verbose examples. ```rust use crossterm::terminal::{terminal,ClearType}; diff --git a/crossterm_terminal/examples/ct_terminal.rs b/crossterm_terminal/examples/ct_terminal.rs deleted file mode 100644 index 20b586c..0000000 --- a/crossterm_terminal/examples/ct_terminal.rs +++ /dev/null @@ -1,131 +0,0 @@ -//! -//! Terminal Examples -//! -#![allow(unused_must_use)] - -use crossterm_cursor::cursor; -use crossterm_terminal::{terminal, ClearType}; - -fn print_test_data() { - for i in 0..100 { - println!("Test data to test terminal: {}", i); - } -} - -/// Clear all lines in terminal | demonstration -pub fn clear_all_lines() { - let terminal = terminal(); - - print_test_data(); - - // Clear all lines in terminal; - terminal.clear(ClearType::All); -} - -/// Clear all lines from cursor position X:4, Y:4 down | demonstration -pub fn clear_from_cursor_down() { - let terminal = terminal(); - - print_test_data(); - - // Set terminal cursor position (see example for more info). - cursor().goto(4, 8); - - // Clear all cells from current cursor position down. - terminal.clear(ClearType::FromCursorDown); -} - -/// Clear all lines from cursor position X:4, Y:4 up | demonstration -pub fn clear_from_cursor_up() { - let terminal = terminal(); - - print_test_data(); - - // Set terminal cursor position (see example for more info). - cursor().goto(4, 4); - - // Clear all cells from current cursor position down. - terminal.clear(ClearType::FromCursorUp); -} - -/// Clear all lines from cursor position X:4, Y:4 up | demonstration -pub fn clear_current_line() { - let terminal = terminal(); - - print_test_data(); - - // Set terminal cursor position (see example for more info). - cursor().goto(4, 3); - - // Clear current line cells. - terminal.clear(ClearType::CurrentLine); -} - -/// Clear all lines from cursor position X:4, Y:7 up | demonstration -pub fn clear_until_new_line() { - let terminal = terminal(); - - print_test_data(); - - // Set terminal cursor position (see example for more info). - cursor().goto(4, 20); - - // Clear all the cells until next line. - terminal.clear(ClearType::UntilNewLine); -} - -/// Print the the current terminal size | demonstration. -pub fn print_terminal_size() { - let terminal = terminal(); - - // Get terminal size - let (width, height) = terminal.terminal_size(); - - // Print results - print!("X: {}, y: {}", width, height); -} - -/// Set the terminal size to width 10, height: 10 | demonstration. -pub fn set_terminal_size() { - let terminal = terminal(); - - terminal.set_size(10, 10); -} - -/// Scroll down 10 lines | demonstration. -pub fn scroll_down() { - let terminal = terminal(); - - print_test_data(); - - // Scroll down 10 lines. - terminal.scroll_down(10); -} - -/// Scroll down 10 lines | demonstration. -pub fn scroll_up() { - let terminal = terminal(); - - print_test_data(); - - // Scroll up 10 lines. - terminal.scroll_up(5); -} - -/// Resize the terminal to X: 10, Y: 10 | demonstration. -pub fn resize_terminal() { - let terminal = terminal(); - - // Get terminal size - terminal.set_size(10, 10); -} - -/// exit the current proccess. -pub fn exit() { - let terminal = terminal(); - terminal.exit(); -} - -fn main() { - resize_terminal() -} diff --git a/crossterm_winapi/README.md b/crossterm_winapi/README.md index 4413a9e..172aac7 100644 --- a/crossterm_winapi/README.md +++ b/crossterm_winapi/README.md @@ -31,7 +31,7 @@ _The following WinApi calls_ - ReadConsoleW # Example -The [examples](./examples) folder has more complete and verbose examples. +The [examples](https://github.com/TimonPost/crossterm/tree/master/examples) folder has more complete and verbose examples. ## Screenbuffer information ```rust diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index d58e327..7f24296 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -147,7 +147,7 @@ The alternate buffer is exactly the dimensions of the window, without any scroll For an example of this behavior, consider when vim is launched from bash. Vim uses the entirety of the screen to edit the file, then returning to bash leaves the original buffer unchanged. -I Highly recommend you to check the `examples/Crossterm 0.3.0/program_examples/first_depth_search` for seeing this in action. +I Highly recommend you to check the `examples/program_examples/first_depth_search` for seeing this in action. ## Raw screen This crate now supports raw screen for both windows and unix systems. @@ -171,7 +171,7 @@ With these modes you can easier design the terminal screen. ## Examples Added [examples](https://github.com/TimonPost/crossterm/tree/master/examples) for each version of the crossterm version. -Also added a folder with some [real life examples](https://github.com/TimonPost/crossterm/tree/master/examples/Crossterm%200.3.0/program_examples). +Also added a folder with some [real life examples](https://github.com/TimonPost/crossterm/tree/master/examples/program_examples). ## Context @@ -226,7 +226,7 @@ Because this looks a little odd I will provide a type withs will manage the `Con ### Alternate screen When you want to switch to alternate screen there are a couple of things to keep in mind for it to work correctly. -First off some code of how to switch to Alternate screen, for more info check the [alternate screen example](https://github.com/TimonPost/crossterm/blob/master/examples/Crossterm%200.3.0/terminal/alternate_screen.rs). +First off some code of how to switch to Alternate screen, for more info check the [alternate screen example](https://github.com/TimonPost/crossterm/blob/master/examples/alternate_screen.rs). _Create alternate screen from `Context`_ diff --git a/docs/Contributing.md b/docs/Contributing.md index 094746a..d4aa528 100644 --- a/docs/Contributing.md +++ b/docs/Contributing.md @@ -37,4 +37,14 @@ The above structure is the same for the other modules. Why I have chosen for this design: - Because you can easily extend to multiple platforms by implementing the trait int the mod.rs. - You keep the functionalities for different platforms separated in different files. -- Also, you have one API the user can call like in the `cursor.rs` above. This file should be avoided to change that much. All the other code could change a lot because it has no impact on the user side. \ No newline at end of file +- Also, you have one API the user can call like in the `cursor.rs` above. This file should be avoided to change that much. All the other code could change a lot because it has no impact on the user side. + +# Import Order +All imports are semantically ordered. The order is: + +- standard library +- external crates +- crate +- super +- self +- mod \ No newline at end of file diff --git a/docs/mdbook/src/SUMMARY.md b/docs/mdbook/src/SUMMARY.md index 5e47232..c3e7fc7 100644 --- a/docs/mdbook/src/SUMMARY.md +++ b/docs/mdbook/src/SUMMARY.md @@ -1,5 +1,7 @@ -# Summary -This book will cover styling, user input, terminal modes, and feature flags. +# Crossterm +This book explains how crossterm works, and how you can use different functionalities. +We look at how to turn feature flags features on and off, how to style the terminal with colors and attributes, +how to read user input and how to make using crossterm easier. - [Feature Flags](feature_flags.md) - [Command API](command.md) diff --git a/docs/mdbook/src/input.md b/docs/mdbook/src/input.md index 2c645fa..dbe446b 100644 --- a/docs/mdbook/src/input.md +++ b/docs/mdbook/src/input.md @@ -1,5 +1,5 @@ Crossterm provides a way to work with the terminal input. We will not cover the basic usage but instead asynchronous and synchronous reading of input. -Please check out these [examples](https://github.com/TimonPost/crossterm/blob/master/examples/input/keyboard/input.rs) for reading a line or a character from the user. +Please check out these [examples](https://github.com/TimonPost/crossterm/blob/master/examples/input.rs) for reading a line or a character from the user. ## Differences Synchronous and Asynchronous Crossterm provides two ways to read user input, synchronous and asynchronous. diff --git a/docs/mdbook/src/styling.md b/docs/mdbook/src/styling.md index 4cd27ac..6f6cc47 100644 --- a/docs/mdbook/src/styling.md +++ b/docs/mdbook/src/styling.md @@ -21,7 +21,7 @@ There are 16 base colors which available for almost all terminals even windows 7 In addition to 16 colors, most UNIX terminals and Windows 10 consoles are also supporting more colors. Those colors could be: [True color (24-bit)](https://en.wikipedia.org/wiki/Color_depth#True_color_(24-bit)) coloring scheme, which allows you to use [RGB](https://nl.wikipedia.org/wiki/RGB-kleursysteem), and [256 (Xterm, 8-bit)](https://jonasjacek.github.io/colors/) colors. -Checkout the examples on how to use this feature. +Checkout the [examples](https://github.com/TimonPost/crossterm/blob/master/examples/style.rs) on how to use this feature. ## Attributes Only UNIX and Windows 10 terminals are supporting attributes on top of the text. Crossterm allows you to add attributes to the text. diff --git a/examples/README.md b/examples/README.md index d8da784..4de086a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,14 +1,24 @@ -This folder contains examples for version 0.3.0 Here you will find examples of all the functionalities crossterm offers. +This folder contains examples for crossterm and it's the sub-crates. -- `color`: this is about the styling of the terminal -- `cursor`: this is about the actions you can perform with the cursor -- `terminal`: this is about the actions you can perform on the terminal -- `input`: this is about input reading -- `key_events`: this is about reading key events -- `crossterm`: this is about the struct `Crossterm` -- `alternate_screen`: this is about switching to an alternate screen buffer -- `raw_screen`: this is about enabling raw screen -- `command`: this is about to the command api -- `program examples`: this folder will contain some real life examples -- `command_bar`: this is a terminal application where multiple threads write to the output while you can enter - commands asynchronously +When using a sub-crate instead of the crossterm crate, make sure to change the namespaces in the examples from `crossterm` to `crossterm_{crate_name}`. + +Examples, on the different functionalities +- [crossterm style](https://crates.io/crates/crossterm_style) + - [color](https://github.com/TimonPost/crossterm/blob/master/examples/cursor.rs): this is about the styling of the terminal +- [crossterm input](https://crates.io/crates/crossterm_input) + - [input](https://github.com/TimonPost/crossterm/blob/master/examples/input.rs): this is about input reading + - [key_events](https://github.com/TimonPost/crossterm/blob/master/examples/key_events.rs): this is about reading key events +- [crossterm screen](https://crates.io/crates/crossterm_screen) + - [alternate_screen](https://github.com/TimonPost/crossterm/blob/master/examples/alternate_screen.rs): this is about switching to an alternate screen buffer + - [raw_screen](https://github.com/TimonPost/crossterm/blob/master/examples/raw_screen.rs): this is about enabling raw screen +- [crossterm cursor](https://crates.io/crates/crossterm_cursor) + - [cursor](https://github.com/TimonPost/crossterm/blob/master/examples/cursor.rs): this is about the actions you can perform with the cursor +- [crossterm terminal](https://crates.io/crates/crossterm_terminal) + - [terminal](https://github.com/TimonPost/crossterm/blob/master/examples/terminal.rs): this is about the actions you can perform on the terminal + +Other +- [crossterm](https://github.com/TimonPost/crossterm/blob/master/examples/crossterm.rs): this is about the struct `Crossterm` +- [command](https://github.com/TimonPost/crossterm/blob/master/examples/command.rs): this is about to the command api +- [program examples](https://github.com/TimonPost/crossterm/tree/master/examples/program_examples): this folder will contain some real life examples +- [command_bar](https://github.com/TimonPost/crossterm/tree/master/examples/command_bar): this is a terminal application where multiple threads write to the output while you can enter + commands asynchronously. diff --git a/examples/alternate_screen.rs b/examples/alternate_screen.rs index c169625..faf7927 100644 --- a/examples/alternate_screen.rs +++ b/examples/alternate_screen.rs @@ -42,6 +42,7 @@ pub fn print_wait_screen_on_alternate_window() -> io::Result<()> { Ok(()) } +// cargo run --example alternate_screen fn main() { print_wait_screen_on_alternate_window().unwrap(); } diff --git a/examples/command.rs b/examples/command.rs index 44848d1..111f017 100644 --- a/examples/command.rs +++ b/examples/command.rs @@ -72,4 +72,5 @@ fn later_execution_command_directly_using_macros() { let _ = stdout.flush(); } +// cargo run --example command fn main() {} diff --git a/examples/command_bar.rs b/examples/command_bar.rs index 3ba0229..9847a2e 100644 --- a/examples/command_bar.rs +++ b/examples/command_bar.rs @@ -6,6 +6,7 @@ use crossterm::{ TerminalCursor, }; +// cargo run --example command_bar fn main() { let _screen = RawScreen::into_raw_mode(); cursor().hide().expect("Couldn't hide cursor"); diff --git a/examples/crossterm.rs b/examples/crossterm.rs index f235f7a..dcf5ee9 100644 --- a/examples/crossterm.rs +++ b/examples/crossterm.rs @@ -4,6 +4,7 @@ use crossterm::{Color, Crossterm}; // use the `Crossterm` to get an instance to the cursor module | demonstration. +// cargo run --example crossterm fn main() { // Create the crossterm type to access different modules. let crossterm = Crossterm::new(); diff --git a/examples/cursor.rs b/examples/cursor.rs index c929671..fd3ac6d 100644 --- a/examples/cursor.rs +++ b/examples/cursor.rs @@ -90,6 +90,7 @@ pub fn blink_cursor() { cursor.blink(false).unwrap(); } +// cargo run --example cursor fn main() { hide_cursor() } diff --git a/examples/key_events.rs b/examples/key_events.rs index ead57e8..868d8f3 100644 --- a/examples/key_events.rs +++ b/examples/key_events.rs @@ -123,9 +123,8 @@ pub fn read_synchronously() { } // <=== raw modes will be disabled here } +// cargo run --example key_events fn main() { - // un-comment below and run with - // `cargo run --example key_events`: // read_synchronously(); - read_asynchronously(); + // read_asynchronously(); } diff --git a/examples/raw_mode.rs b/examples/raw_mode.rs index 6703b42..7128c89 100644 --- a/examples/raw_mode.rs +++ b/examples/raw_mode.rs @@ -48,6 +48,7 @@ pub fn print_wait_screen_on_alternate_window() -> io::Result<()> { Ok(()) } +// cargo run --example raw_mode fn main() { print_wait_screen_on_alternate_window().unwrap(); } diff --git a/examples/style.rs b/examples/style.rs index 92db79c..a3ee9fe 100644 --- a/examples/style.rs +++ b/examples/style.rs @@ -408,6 +408,7 @@ pub fn reset_fg_and_bg() { println!("{}", Colored::Bg(Color::Reset)); } +// cargo run --example style fn main() { print_all_background_colors_with_method() } diff --git a/examples/terminal.rs b/examples/terminal.rs index dcd5832..0ec6740 100644 --- a/examples/terminal.rs +++ b/examples/terminal.rs @@ -134,6 +134,7 @@ pub fn exit() { terminal.exit(); } +// cargo run --example terminal fn main() { let _ = scroll_down(); }