Struct Printer

pub struct Printer<'a, 'b> {
    pub offset: XY<usize>,
    pub output_size: XY<usize>,
    pub size: XY<usize>,
    pub content_offset: XY<usize>,
    pub focused: bool,
    pub enabled: bool,
    pub theme: &'a Theme,
    /* private fields */
}

Convenient interface to draw on a subset of the screen.

The printing area is defined by offset and size.
The content that will be printed is defined by Self::content_offset and Self::size.

If the printer is asked to print outside of the printing area, then the string to be printed shall be truncated without throwing errors. Refer to the crate::traits::View to understand how to change its size.

Fields

offset: XY<usize>

Offset into the window this printer should start drawing at.

A print request at x will really print at x + offset.

output_size: XY<usize>

Size of the area we are allowed to draw on.

Anything outside of this should be discarded.
The view being drawn can ignore this, but anything further than that will be ignored.

size: XY<usize>

Size allocated to the view.

This should be the same value as the one given in the last call to View::layout.

content_offset: XY<usize>

Offset into the view for this printer.

The view being drawn can ignore this, but anything to the top-left of this will actually be ignored, so it can be used to skip this part.

A print request x, will really print at x - content_offset.

focused: bool

Whether the view to draw is currently focused or not.

enabled: bool

Whether the view to draw is currently enabled or not.

theme: &'a Theme

Currently used theme

Implementations

impl<'a, 'b> Printer<'a, 'b>

pub fn output_window(&self) -> Rect

Returns the region of the window where this printer can write.

pub fn buffer_size(&self) -> XY<usize>

Returns the size of the entire buffer.

This is the size of the entire terminal, not just the area this printer can write into.

pub fn clear(&self)

Clear the screen.

It will discard anything drawn before.

Users rarely need to call this directly.

pub fn print_styled<V, S>(&self, start: V, text: S)

where V: Into<XY<usize>>, S: SpannedText<S = IndexedSpan<Style>>,

Prints some styled text at the given position.

pub fn print<S>(&self, start: S, text: &str)

where S: Into<XY<usize>>,

Prints some text at the given position.

Parameters

• start is the offset used to print the text in the view.
• text is a string to print on the screen. It must be a single line, no line wrapping will be done.

Description

Prints some text at the given position. The text could be truncated if it exceed the drawing area size.

Example

use cursive::{Printer, Vec2, View, XY};

pub struct CustomView {
    word: String,
}

impl CustomView {
    pub fn new() -> Self {
        Self {
            word: String::from("Eh, tu connais Rust?"),
        }
    }
}

impl View for CustomView {
    fn draw(&self, printer: &Printer<'_, '_>) {
        printer.print(XY::new(0, 0), &self.word);
    }
}

pub fn print_vline<T>(&self, start: T, height: usize, c: &str)

where T: Into<XY<usize>>,

Prints a vertical line using the given character.

pub fn on_window<F, R>(&self, f: F) -> R

where F: FnOnce(&mut Window<'_>) -> R,

Calls a closure on the output window for this printer.

pub fn print_line<T>( &self, orientation: Orientation, start: T, length: usize, c: &str, )

where T: Into<XY<usize>>,

Prints a line using the given character.

pub fn print_rect(&self, rect: Rect, c: &str)

Fills a rectangle using the given character.

pub fn print_hline<T>(&self, start: T, width: usize, c: &str)

where T: Into<XY<usize>>,

Prints a horizontal line using the given character.

pub fn current_color(&self) -> ColorPair

Returns the color currently used by the printer.

pub fn current_style(&self) -> ConcreteStyle

Returns the style currently used by the printer.

pub fn set_color(&mut self, color: ColorStyle)

Sets the color used by this printer.

pub fn set_style<T>(&mut self, style: T)

where T: Into<StyleType>,

Sets the current style used by the printer.

pub fn unset_effect(&mut self, effect: Effect)

Deactivate the given effect for this printer.

pub fn set_effect(&mut self, effect: Effect)

Active the given effect for this printer.

pub fn with_color<F>(&self, c: ColorStyle, f: F)

where F: FnOnce(&Printer<'_, '_>),

Call the given closure with a colored printer, that will apply the given color on prints.

Does not change the current set of active effects (bold/underline/…).

pub fn with_style<F, T>(&self, style: T, f: F)

where F: FnOnce(&Printer<'_, '_>), T: Into<StyleType>,

Call the given closure with a styled printer, that will apply the given style on prints.

Examples

printer.with_style(style::PaletteStyle::Highlight, |printer| {
    printer.print((0, 0), "This text is highlighted!");
});

pub fn with_effect<F>(&self, effect: Effect, f: F)

where F: FnOnce(&Printer<'_, '_>),

Call the given closure with a modified printer that will apply the given effect on prints.

pub fn with_theme<F>(&self, theme: &Theme, f: F)

where F: FnOnce(&Printer<'_, '_>),

Call the given closure with a modified printer that will apply the given theme on prints.

pub fn theme<'c>(&self, theme: &'c Theme) -> Printer<'c, 'b>

where 'a: 'c,

Create a new sub-printer with the given theme.

pub fn with_effects<F>(&self, effects: EnumSet<Effect>, f: F)

where F: FnOnce(&Printer<'_, '_>),

Call the given closure with a modified printer that will apply each given effect on prints.

Note that this does not unset any active effect.

pub fn print_box<T, S>(&self, start: T, size: S, invert: bool)

where T: Into<XY<usize>>, S: Into<XY<usize>>,

Prints a rectangular box.

If invert is true, and the theme uses Outset borders, then the box will use an “inset” style instead.

Examples

printer.print_box((0, 0), (6, 4), false);

pub fn with_high_border<F>(&self, invert: bool, f: F)

where F: FnOnce(&Printer<'_, '_>),

Runs the given function using a color depending on the theme.

• If the theme’s borders is None, return without calling f.
• If the theme’s borders is “outset” and invert is false, use PaletteStyle::Tertiary.
• Otherwise, use PaletteStyle::Primary.

pub fn with_low_border<F>(&self, invert: bool, f: F)

where F: FnOnce(&Printer<'_, '_>),

Runs the given function using a color depending on the theme.

• If the theme’s borders is None, return without calling f.
• If the theme’s borders is “outset” and invert is true, use PaletteStyle::Tertiary.
• Otherwise, use PaletteStyle::Primary.

pub fn with_selection<F>(&self, selection: bool, f: F)

where F: FnOnce(&Printer<'_, '_>),

Apply a selection style and call the given function.

• If selection is false, simply uses the current style.
• If selection is true:
  • If the printer currently has the focus, uses PaletteStyle::Highlight.
  • Otherwise, uses PaletteStyle::HighlightInactive.

pub fn print_hdelim<T>(&self, start: T, len: usize)

where T: Into<XY<usize>>,

Prints a horizontal delimiter with side border ├ and ┤.

pub fn offset<S>(&self, offset: S) -> Printer<'a, 'b>

where S: Into<XY<usize>>,

Returns a sub-printer with the given offset.

It will print in an area slightly to the bottom/right.

pub fn focused(&self, focused: bool) -> Printer<'a, 'b>

Returns a new sub-printer inheriting the given focus.

If self is focused and focused == true, the child will be focused.

Otherwise, he will be unfocused.

pub fn enabled(&self, enabled: bool) -> Printer<'a, 'b>

Returns a new sub-printer inheriting the given enabled state.

If self is enabled and enabled == true, the child will be enabled.

Otherwise, he will be disabled.

pub fn windowed(&self, viewport: Rect) -> Printer<'a, 'b>

Returns a new sub-printer for the given viewport.

This is a combination of offset + cropped.

pub fn cropped<S>(&self, size: S) -> Printer<'a, 'b>

where S: Into<XY<usize>>,

Returns a new sub-printer with a cropped area.

The new printer size will be the minimum of size and its current size.
Any size reduction happens at the bottom-right.

pub fn cropped_centered<S>(&self, size: S) -> Printer<'a, 'b>

where S: Into<XY<usize>>,

Returns a new sub-printer with a cropped area.

The new printer size will be the minimum of size and its current size.
The view will stay centered.
Note that if shrinking by an odd number, the view will round to the top-left.

pub fn shrinked<S>(&self, borders: S) -> Printer<'a, 'b>

where S: Into<XY<usize>>,

Returns a new sub-printer with a shrinked area.

The printer size will be reduced by the given border from the bottom-right.

pub fn shrinked_centered<S>(&self, borders: S) -> Printer<'a, 'b>

where S: Into<XY<usize>>,

Returns a new sub-printer with a shrinked area.

The printer size will be reduced by the given border, and will stay centered.
Note that if shrinking by an odd number, the view will round to the top-left.

pub fn content_offset<S>(&self, offset: S) -> Printer<'a, 'b>

where S: Into<XY<usize>>,

Returns a new sub-printer with a content offset.

This is useful for parent views that only show a subset of their child, like crate::views::ScrollView.

pub fn inner_size<S>(&self, size: S) -> Printer<'a, 'b>

where S: Into<XY<usize>>,

Returns a sub-printer with a different inner size.

This will not change the actual output size, but will appear bigger (or smaller) to users of this printer.
Useful to give to children who think they’re big, but really aren’t.

Trait Implementations

impl<'a, 'b> Clone for Printer<'a, 'b>

fn clone(&self) -> Printer<'a, 'b>

Returns a copy of the value.

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

Performs copy-assignment from source.