Struct minus::Pager

pub struct Pager { /* private fields */ }

A pager acts as a middleman for communication between the main application and the user with the core functions of minus

It consists of a crossbeam_channel::Sender and crossbeam_channel::Receiver pair. When a method like set_text or push_str is called, the function takes the input. wraps it in the appropriate event type and transmits it through the sender held inside the this.

The receiver part of the channel is continuously polled by the pager for events. Depending on the type of event that occurs, the pager will either redraw the screen or update the PagerState

Implementations

impl Pager

pub fn new() -> Self

Initialize a new pager

Example

let pager = minus::Pager::new();

pub fn set_text(&self, s: impl Into<String>) -> Result<(), MinusError>

Set the output text to this t

Note that unlike Pager::push_str, this replaces the original text. If you want to append text, use the Pager::push_str function or the write!/writeln! macros

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

let pager = minus::Pager::new();
pager.set_text("This is a line").expect("Failed to send data to the pager");

pub fn push_str(&self, s: impl Into<String>) -> Result<(), MinusError>

Appends text to the pager output.

You can also use write!/writeln! macros to append data to the pager. The implementation basically calls this function internally.

One difference between using the macros and this function is that this does not require Pager to be declared mutable while in order to use the macros, you need to declare the Pager as mutable.

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use std::fmt::Write;

let mut pager = minus::Pager::new();
pager.push_str("This is some text").expect("Failed to send data to the pager");
// This is same as above
write!(pager, "This is some text").expect("Failed to send data to the pager");

pub fn set_line_numbers(&self, l: LineNumbers) -> Result<(), MinusError>

Set line number configuration for the pager

See LineNumbers for available options

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::{Pager, LineNumbers};

let pager = Pager::new();
pager.set_line_numbers(LineNumbers::Enabled).expect("Failed to send data to the pager");

pub fn set_prompt(&self, text: impl Into<String>) -> Result<(), MinusError>

Set the text displayed at the bottom prompt

Panics

This function panics if the given text contains newline characters. This is because, the pager reserves only one line for showing the prompt and a newline will cause it to span multiple lines, breaking the display

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::Pager;

let pager = Pager::new();
pager.set_prompt("my prompt").expect("Failed to send data to the pager");

pub fn send_message(&self, text: impl Into<String>) -> Result<(), MinusError>

Display a temporary message at the prompt area

Panics

This function panics if the given text contains newline characters. This is because, the pager reserves only one line for showing the prompt and a newline will cause it to span multiple lines, breaking the display

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::Pager;

let pager = Pager::new();
pager.send_message("An error occurred").expect("Failed to send data to the pager");

pub fn set_exit_strategy(&self, es: ExitStrategy) -> Result<(), MinusError>

Set the default exit strategy.

This controls how the pager will behave when the user presses q or Ctrl+C. See ExitStrategy for available options

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

use minus::{Pager, ExitStrategy};

let pager = Pager::new();
pager.set_exit_strategy(ExitStrategy::ProcessQuit).expect("Failed to send data to the pager");

pub fn set_run_no_overflow(&self, val: bool) -> Result<(), MinusError>

Available on crate feature static_output only.

Set whether to display pager if there’s less data than available screen height

When this is set to false, the pager will simply print all the lines to the main screen and immediately quit if the number of lines to display is less than the available columns in the terminal. Setting this to true will cause a full pager to start and display the data even if there is less number of lines to display than available rows.

This is only available in static output mode as the size of the data is known beforehand. In async output the pager can receive more data anytime

By default this is set to false

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

use minus::Pager;

let pager = Pager::new();
pager.set_run_no_overflow(true).expect("Failed to send data to the pager");

pub fn set_input_classifier( &self, handler: Box<dyn InputClassifier + Send + Sync> ) -> Result<(), MinusError>

Set a custom input classifier function.

When the pager encounters a user input, it calls the input classifier with the event and PagerState as parameters.

A input classifier is a type implementing the InputClassifier trait. It only has one required function, InputClassifier::classify_input which matches user input events and maps them to a InputEvents.

See the InputHandler trait for information about implementing it.

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

pub fn add_exit_callback( &self, cb: Box<dyn FnMut() + Send + Sync + 'static> ) -> Result<(), MinusError>

Adds a function that will be called when the user quits the pager

Multiple functions can be stored for calling when the user quits. These functions run sequentially in the order they were added

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the receiver

Example

use minus::Pager;

fn hello() {
    println!("Hello");
}

let pager = Pager::new();
pager.add_exit_callback(Box::new(hello)).expect("Failed to send data to the pager");

pub fn set_incremental_search_condition( &self, cb: Box<dyn Fn(&SearchOpts<'_>) -> bool + Send + Sync + 'static> ) -> Result<(), MinusError>

Available on crate feature search only.

Override the condition for running incremental search

See Incremental Search to know more on how this works

Errors

This function will returns a Err(MinusError::Communication) if the data could not be send to the receiver end.

pub fn show_prompt(&self, show: bool) -> Result<(), MinusError>

Control whether to show the prompt

Many applications don’t want the prompt to be displayed at all. This function can be used to completely turn off the prompt. Passing false to this will stops the prompt from displaying and instead a blank line will be displayed.

Note that This merely stop the prompt from being shown. Your application can still update the prompt and send messages to the user but it won’t be shown until the prompt isn’t re-enabled. The prompt section will also be used when user opens the search prompt to type a search query.

Errors

This function will return a Err(MinusError::Communication) if the data could not be sent to the mus’s receiving end

Example

use minus::Pager;

let pager = Pager::new();
pager.show_prompt(false).unwrap();

Trait Implementations

impl Clone for Pager

fn clone(&self) -> Pager

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Pager

fn default() -> Self

Returns the “default value” for a type.

impl Write for Pager

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.