Struct embedded_graphics::primitives::rectangle::Rectangle

pub struct Rectangle {
    pub top_left: Point,
    pub size: Size,
}

Rectangle primitive

Examples

Create some rectangles with different styles

use embedded_graphics::{
    pixelcolor::Rgb565, prelude::*, primitives::{Rectangle, PrimitiveStyleBuilder},
};

// Rectangle with red 3 pixel wide stroke and green fill with the top left corner at (30, 20) and
// a size of (10, 15)
let style = PrimitiveStyleBuilder::new()
    .stroke_color(Rgb565::RED)
    .stroke_width(3)
    .fill_color(Rgb565::GREEN)
    .build();

Rectangle::new(Point::new(30, 20), Size::new(10, 15))
    .into_styled(style)
    .draw(&mut display)?;

// Rectangle with translation applied
Rectangle::new(Point::new(30, 20), Size::new(10, 15))
    .translate(Point::new(-20, -10))
    .into_styled(style)
    .draw(&mut display)?;

Fields

top_left: Point

Top left point of the rectangle.

size: Size

Size of the rectangle.

Implementations

impl Rectangle

pub const fn new(top_left: Point, size: Size) -> Rectangle

Creates a new rectangle from the top left point and the size.

pub fn with_corners(corner_1: Point, corner_2: Point) -> Rectangle

Creates a new rectangle from two corners.

pub fn with_center(center: Point, size: Size) -> Rectangle

Creates a new rectangle from the center point and the size.

For rectangles with even width and/or height the top left corner doesn’t align with the pixel grid. Because of this the coordinates of the top left corner will be rounded up to the nearest integer coordinate.

pub const fn zero() -> Rectangle

Returns a zero sized rectangle.

pub fn center(&self) -> Point

Returns the center of this rectangle.

For rectangles with even width and/or height the returned value is rounded down to the nearest integer coordinate.

pub fn bottom_right(&self) -> Option<Point>

Returns the bottom right corner of this rectangle.

Because the smallest rectangle that can be represented by its corners has a size of 1 x 1 pixels, this function returns None if the width or height of the rectangle is zero.

pub fn contains(&self, point: Point) -> bool

Return whether the rectangle contains a given point.

pub fn intersection(&self, other: &Rectangle) -> Rectangle

Returns a new Rectangle containing the intersection of self and other.

If no intersection is present, this method will return a zero sized rectangle.

Examples

Intersection

This example draws two rectangles to a mock display using the . character, along with their intersection shown with # characters.

use embedded_graphics::{
    mock_display::MockDisplay, pixelcolor::BinaryColor, prelude::*,
    primitives::{Rectangle, PrimitiveStyle},
};

let mut display = MockDisplay::new();

let rect1 = Rectangle::new(Point::zero(), Size::new(7, 8));
let rect2 = Rectangle::new(Point::new(2, 3), Size::new(10, 7));

let intersection = rect1.intersection(&rect2);

rect1
    .into_styled(PrimitiveStyle::with_stroke(BinaryColor::Off, 1))
    .draw(&mut display)?;

rect2
    .into_styled(PrimitiveStyle::with_stroke(BinaryColor::Off, 1))
    .draw(&mut display)?;

intersection
    .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
    .draw(&mut display)?;

display.assert_pattern(&[
    ".......     ",
    ".     .     ",
    ".     .     ",
    ". #####.....",
    ". #   #    .",
    ". #   #    .",
    ". #   #    .",
    "..#####    .",
    "  .        .",
    "  ..........",
]);

No intersection

This example creates two rectangles with no intersection between them. In this case, intersection returns a zero-sized rectangle.

use embedded_graphics::{prelude::*, primitives::{Rectangle, PrimitiveStyle}};

let rect1 = Rectangle::new(Point::zero(), Size::new(7, 8));
let rect2 = Rectangle::new(Point::new(10, 15), Size::new(10, 7));

let intersection = rect1.intersection(&rect2);

assert!(intersection.is_zero_sized());

pub fn resized(&self, size: Size, anchor_point: AnchorPoint) -> Rectangle

Returns a resized copy of this rectangle.

The rectangle is resized relative to the given anchor point.

Examples

use embedded_graphics::{
    prelude::*,
    primitives::rectangle::Rectangle,
    geometry::AnchorPoint,
};

let rect = Rectangle::new(Point::new(20, 20), Size::new(10, 20));
let resized = rect.resized(Size::new(20, 10), AnchorPoint::Center);

assert_eq!(
    resized,
    Rectangle::new(Point::new(15, 25), Size::new(20, 10))
);

pub fn offset(&self, offset: i32) -> Rectangle

Offset the rectangle by a given value.

Negative values will shrink the rectangle.

pub fn anchor_point(&self, anchor_point: AnchorPoint) -> Point

Returns an anchor point.

Examples

use embedded_graphics::{
    prelude::*,
    primitives::rectangle::Rectangle,
    geometry::AnchorPoint,
};

let mut rect = Rectangle::new(Point::new(20, 20), Size::new(11, 21));

assert_eq!(rect.anchor_point(AnchorPoint::TopLeft), Point::new(20, 20));
assert_eq!(
    rect.anchor_point(AnchorPoint::BottomCenter),
    Point::new(25, 40)
);

pub fn rows(&self) -> Range<i32>

Returns the range of Y coordinates in this rectangle.

Examples

use embedded_graphics::{prelude::*, primitives::Rectangle};

let rect = Rectangle::new(Point::new(10, 20), Size::new(3, 4));
assert_eq!(rect.rows(), 20..24);

By combining this method with columns it is possible to iterate over all pixels inside the rectangle. This can be more flexible than using the points iterator, for example, if a different iteration order is required or some operations should be called once per row.

use embedded_graphics::{prelude::*, primitives::Rectangle};

let rect = Rectangle::new(Point::new(10, 20), Size::new(3, 4));

// Iterate over the y coordinates of the rows in reverse order.
for y in rect.rows().rev() {
    for x in rect.columns() {
        // use x, y coordinates
    }
}

pub fn columns(&self) -> Range<i32>

Returns the range of X coordinates in this rectangle.

Examples

use embedded_graphics::{prelude::*, primitives::Rectangle};

let rect = Rectangle::new(Point::new(10, 20), Size::new(3, 4));

assert_eq!(rect.columns(), 10..13);

By combining this method with rows it is possible to iterator over all pixels inside the rectangle. This can be more flexible than using the points iterator, for example, if a different iteration order is required or some operations should be called once per row.

use embedded_graphics::{prelude::*, primitives::Rectangle};

let rect = Rectangle::new(Point::new(10, 20), Size::new(3, 4));

// Iterate over all points starting from the top right corner and advancing downwards.
for x in rect.columns().rev() {
    for y in rect.rows() {
        // use x, y coordinates
    }
}

pub fn is_zero_sized(&self) -> bool

Returns true is the rectangle is zero sized.

A rectangle is zero sized if the width or height are zero.

Examples

use embedded_graphics::{prelude::*, primitives::Rectangle};

let rect = Rectangle::new(Point::new(10, 20), Size::new(10, 20));
assert_eq!(rect.is_zero_sized(), false);

let rect = Rectangle::new(Point::new(10, 20), Size::zero());
assert_eq!(rect.is_zero_sized(), true);

Trait Implementations

impl Clone for Rectangle

pub fn clone(&self) -> Rectangle

Returns a copy of the value.

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

Performs copy-assignment from source.

impl ContainsPoint for Rectangle

fn contains(&self, point: Point) -> bool

Returns true if the given point is inside the shape.

impl Copy for Rectangle

impl Debug for Rectangle

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Rectangle

pub fn default() -> Rectangle

Returns the “default value” for a type.

impl Dimensions for Rectangle

pub fn bounding_box(&self) -> Rectangle

Returns the bounding box.

impl Eq for Rectangle

impl Hash for Rectangle

pub fn hash<__H>(&self, state: &mut __H) where
    __H: Hasher, 

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl OffsetOutline for Rectangle

fn offset(&self, offset: i32) -> Self

Offsets the outline of the shape.

impl Ord for Rectangle

pub fn cmp(&self, other: &Rectangle) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Rectangle> for Rectangle

pub fn eq(&self, other: &Rectangle) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &Rectangle) -> bool

This method tests for !=.

impl PartialOrd<Rectangle> for Rectangle

pub fn partial_cmp(&self, other: &Rectangle) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PointsIter for Rectangle

type Iter = Points

Iterator over all points inside the primitive.

pub fn points(&self) -> <Rectangle as PointsIter>::Iter

Returns an iterator over all points inside the primitive.

impl Primitive for Rectangle

fn into_styled<S>(self, style: S) -> Styled<Self, S> where
    Self: Sized, 

Converts this primitive into a Styled.

impl StructuralEq for Rectangle

impl StructuralPartialEq for Rectangle

impl<C: PixelColor> StyledDimensions<PrimitiveStyle<C>> for Rectangle

fn styled_bounding_box(&self, style: &PrimitiveStyle<C>) -> Rectangle

Returns the bounding box using the given style.

impl<C: PixelColor> StyledDrawable<PrimitiveStyle<C>> for Rectangle

type Color = C

Color type.

type Output = ()

Output type.

fn draw_styled<D>(
    &self,
    style: &PrimitiveStyle<C>,
    target: &mut D
) -> Result<Self::Output, D::Error> where
    D: DrawTarget<Color = C>, 

Draws the primitive using the given style.

impl Transform for Rectangle

fn translate(&self, by: Point) -> Self

Translate the rect from its current position to a new position by (x, y) pixels, returning a new Rectangle. For a mutating transform, see translate_mut.

let rect = Rectangle::new(Point::new(5, 10), Size::new(10, 10));
let moved = rect.translate(Point::new(10, 10));

assert_eq!(moved.top_left, Point::new(15, 20));
assert_eq!(moved.size, Size::new(10, 10));

fn translate_mut(&mut self, by: Point) -> &mut Self

Translate the rect from its current position to a new position by (x, y) pixels.

let mut rect = Rectangle::new(Point::new(5, 10), Size::new(10, 10));
rect.translate_mut(Point::new(10, 10));

assert_eq!(rect.top_left, Point::new(15, 20));
assert_eq!(rect.size, Size::new(10, 10));