Rect
Added in version 1.0.
- class Rect(*args, **kwargs)
The location and size of a rectangle region.
The width and height of a Rect
can be negative; for instance,
a Rect
with an origin of [ 0, 0 ] and a size of [ 10, 10 ] is
equivalent to a Rect
with an origin of [ 10, 10 ] and a size
of [ -10, -10 ].
Application code can normalize rectangles using normalize()
;
this function will ensure that the width and height of a rectangle are
positive values. All functions taking a Rect
as an argument
will internally operate on a normalized copy; all functions returning a
Rect
will always return a normalized rectangle.
Methods
- class Rect
- alloc() Rect
Allocates a new
Rect
.The contents of the returned rectangle are undefined.
Added in version 1.0.
- contains_point(p: Point) bool
Checks whether a
Rect
contains the given coordinates.Added in version 1.0.
- Parameters:
p – a
Point
- contains_rect(b: Rect) bool
Checks whether a
Rect
fully contains the given rectangle.Added in version 1.0.
- Parameters:
b – a
Rect
- equal(b: Rect) bool
Checks whether the two given rectangle are equal.
Added in version 1.0.
- Parameters:
b – a
Rect
- expand(p: Point) Rect
Expands a
Rect
to contain the givenPoint
.Added in version 1.4.
- Parameters:
p – a
Point
- get_bottom_left() Point
Retrieves the coordinates of the bottom-left corner of the given rectangle.
Added in version 1.0.
- get_bottom_right() Point
Retrieves the coordinates of the bottom-right corner of the given rectangle.
Added in version 1.0.
- get_center() Point
Retrieves the coordinates of the center of the given rectangle.
Added in version 1.0.
- get_top_left() Point
Retrieves the coordinates of the top-left corner of the given rectangle.
Added in version 1.0.
- get_top_right() Point
Retrieves the coordinates of the top-right corner of the given rectangle.
Added in version 1.0.
- get_x() float
Retrieves the normalized X coordinate of the origin of the given rectangle.
Added in version 1.0.
- get_y() float
Retrieves the normalized Y coordinate of the origin of the given rectangle.
Added in version 1.0.
- init(x: float, y: float, width: float, height: float) Rect
Initializes the given
Rect
with the given values.This function will implicitly normalize the
Rect
before returning.Added in version 1.0.
- Parameters:
x – the X coordinate of the
graphene_rect_t
.originy – the Y coordinate of the
graphene_rect_t
.originwidth – the width of the
graphene_rect_t
.sizeheight – the height of the
graphene_rect_t
.size
- init_from_rect(src: Rect) Rect
Initializes
r
using the givensrc
rectangle.This function will implicitly normalize the
Rect
before returning.Added in version 1.0.
- Parameters:
src – a
Rect
- inset(d_x: float, d_y: float) Rect
Changes the given rectangle to be smaller, or larger depending on the given inset parameters.
To create an inset rectangle, use positive
d_x
ord_y
values; to create a larger, encompassing rectangle, use negatived_x
ord_y
values.The origin of the rectangle is offset by
d_x
andd_y
, while the size is adjusted by(2 * ``d_x`
, 2 *d_y
)`. Ifd_x
andd_y
are positive values, the size of the rectangle is decreased; ifd_x
andd_y
are negative values, the size of the rectangle is increased.If the size of the resulting inset rectangle has a negative width or height then the size will be set to zero.
Added in version 1.0.
- Parameters:
d_x – the horizontal inset
d_y – the vertical inset
- inset_r(d_x: float, d_y: float) Rect
Changes the given rectangle to be smaller, or larger depending on the given inset parameters.
To create an inset rectangle, use positive
d_x
ord_y
values; to create a larger, encompassing rectangle, use negatived_x
ord_y
values.The origin of the rectangle is offset by
d_x
andd_y
, while the size is adjusted by(2 * ``d_x`
, 2 *d_y
)`. Ifd_x
andd_y
are positive values, the size of the rectangle is decreased; ifd_x
andd_y
are negative values, the size of the rectangle is increased.If the size of the resulting inset rectangle has a negative width or height then the size will be set to zero.
Added in version 1.4.
- Parameters:
d_x – the horizontal inset
d_y – the vertical inset
- interpolate(b: Rect, factor: float) Rect
Linearly interpolates the origin and size of the two given rectangles.
Added in version 1.0.
- Parameters:
b – a
Rect
factor – the linear interpolation factor
- intersection(b: Rect) tuple[bool, Rect]
Computes the intersection of the two given rectangles.
The intersection in the image above is the blue outline.
If the two rectangles do not intersect,
res
will contain a degenerate rectangle with origin in (0, 0) and a size of 0.Added in version 1.0.
- Parameters:
b – a
Rect
- normalize() Rect
Normalizes the passed rectangle.
This function ensures that the size of the rectangle is made of positive values, and that the origin is the top-left corner of the rectangle.
Added in version 1.0.
- normalize_r() Rect
Normalizes the passed rectangle.
This function ensures that the size of the rectangle is made of positive values, and that the origin is in the top-left corner of the rectangle.
Added in version 1.4.
- offset(d_x: float, d_y: float) Rect
Offsets the origin by
d_x
andd_y
.The size of the rectangle is unchanged.
Added in version 1.0.
- Parameters:
d_x – the horizontal offset
d_y – the vertical offset
- offset_r(d_x: float, d_y: float) Rect
Offsets the origin of the given rectangle by
d_x
andd_y
.The size of the rectangle is left unchanged.
Added in version 1.4.
- Parameters:
d_x – the horizontal offset
d_y – the vertical offset
- round() Rect
Rounds the origin and size of the given rectangle to their nearest integer values; the rounding is guaranteed to be large enough to have an area bigger or equal to the original rectangle, but might not fully contain its extents. Use
round_extents()
in case you need to round to a rectangle that covers fully the original one.This function is the equivalent of calling
floor
on the coordinates of the origin, andceil
on the size.Added in version 1.4.
Deprecated since version 1.10: Use
round_extents()
instead
- round_extents() Rect
Rounds the origin of the given rectangle to its nearest integer value and and recompute the size so that the rectangle is large enough to contain all the conrners of the original rectangle.
This function is the equivalent of calling
floor
on the coordinates of the origin, and recomputing the size callingceil
on the bottom-right coordinates.If you want to be sure that the rounded rectangle completely covers the area that was covered by the original rectangle — i.e. you want to cover the area including all its corners — this function will make sure that the size is recomputed taking into account the ceiling of the coordinates of the bottom-right corner. If the difference between the original coordinates and the coordinates of the rounded rectangle is greater than the difference between the original size and and the rounded size, then the move of the origin would not be compensated by a move in the anti-origin, leaving the corners of the original rectangle outside the rounded one.
Added in version 1.10.
- round_to_pixel() Rect
Rounds the origin and the size of the given rectangle to their nearest integer values; the rounding is guaranteed to be large enough to contain the original rectangle.
Added in version 1.0.
Deprecated since version 1.4: Use
round()
instead
- scale(s_h: float, s_v: float) Rect
Scales the size and origin of a rectangle horizontaly by
s_h
, and vertically bys_v
. The resultres
is normalized.Added in version 1.10.
- Parameters:
s_h – horizontal scale factor
s_v – vertical scale factor