:right-sidebar: True Rect =================================================================== .. currentmodule:: gi.repository.Graphene .. versionadded:: 1.0 .. class:: Rect(*args, **kwargs) :no-contents-entry: The location and size of a rectangle region. The width and height of a :obj:`~gi.repository.Graphene.Rect` can be negative; for instance, a :obj:`~gi.repository.Graphene.Rect` with an origin of [ 0, 0 ] and a size of [ 10, 10 ] is equivalent to a :obj:`~gi.repository.Graphene.Rect` with an origin of [ 10, 10 ] and a size of [ -10, -10 ]. Application code can normalize rectangles using :func:`~gi.repository.Graphene.Rect.normalize`; this function will ensure that the width and height of a rectangle are positive values. All functions taking a :obj:`~gi.repository.Graphene.Rect` as an argument will internally operate on a normalized copy; all functions returning a :obj:`~gi.repository.Graphene.Rect` will always return a normalized rectangle. Methods ------- .. rst-class:: interim-class .. class:: Rect :no-index: .. classmethod:: alloc() -> ~gi.repository.Graphene.Rect Allocates a new :obj:`~gi.repository.Graphene.Rect`\. The contents of the returned rectangle are undefined. .. versionadded:: 1.0 .. method:: contains_point(p: ~gi.repository.Graphene.Point) -> bool Checks whether a :obj:`~gi.repository.Graphene.Rect` contains the given coordinates. .. versionadded:: 1.0 :param p: a :obj:`~gi.repository.Graphene.Point` .. method:: contains_rect(b: ~gi.repository.Graphene.Rect) -> bool Checks whether a :obj:`~gi.repository.Graphene.Rect` fully contains the given rectangle. .. versionadded:: 1.0 :param b: a :obj:`~gi.repository.Graphene.Rect` .. method:: equal(b: ~gi.repository.Graphene.Rect) -> bool Checks whether the two given rectangle are equal. .. versionadded:: 1.0 :param b: a :obj:`~gi.repository.Graphene.Rect` .. method:: expand(p: ~gi.repository.Graphene.Point) -> ~gi.repository.Graphene.Rect Expands a :obj:`~gi.repository.Graphene.Rect` to contain the given :obj:`~gi.repository.Graphene.Point`\. .. versionadded:: 1.4 :param p: a :obj:`~gi.repository.Graphene.Point` .. method:: free() -> None Frees the resources allocated by :func:`~gi.repository.Graphene.Rect.alloc`. .. versionadded:: 1.0 .. method:: get_area() -> float Compute the area of given normalized rectangle. .. versionadded:: 1.10 .. method:: get_bottom_left() -> ~gi.repository.Graphene.Point Retrieves the coordinates of the bottom-left corner of the given rectangle. .. versionadded:: 1.0 .. method:: get_bottom_right() -> ~gi.repository.Graphene.Point Retrieves the coordinates of the bottom-right corner of the given rectangle. .. versionadded:: 1.0 .. method:: get_center() -> ~gi.repository.Graphene.Point Retrieves the coordinates of the center of the given rectangle. .. versionadded:: 1.0 .. method:: get_height() -> float Retrieves the normalized height of the given rectangle. .. versionadded:: 1.0 .. method:: get_top_left() -> ~gi.repository.Graphene.Point Retrieves the coordinates of the top-left corner of the given rectangle. .. versionadded:: 1.0 .. method:: get_top_right() -> ~gi.repository.Graphene.Point Retrieves the coordinates of the top-right corner of the given rectangle. .. versionadded:: 1.0 .. method:: get_vertices() -> list[~gi.repository.Graphene.Vec2] Computes the four vertices of a :obj:`~gi.repository.Graphene.Rect`\. .. versionadded:: 1.4 .. method:: get_width() -> float Retrieves the normalized width of the given rectangle. .. versionadded:: 1.0 .. method:: get_x() -> float Retrieves the normalized X coordinate of the origin of the given rectangle. .. versionadded:: 1.0 .. method:: get_y() -> float Retrieves the normalized Y coordinate of the origin of the given rectangle. .. versionadded:: 1.0 .. method:: init(x: float, y: float, width: float, height: float) -> ~gi.repository.Graphene.Rect Initializes the given :obj:`~gi.repository.Graphene.Rect` with the given values. This function will implicitly normalize the :obj:`~gi.repository.Graphene.Rect` before returning. .. versionadded:: 1.0 :param x: the X coordinate of the ``graphene_rect_t``\.origin :param y: the Y coordinate of the ``graphene_rect_t``\.origin :param width: the width of the ``graphene_rect_t``\.size :param height: the height of the ``graphene_rect_t``\.size .. method:: init_from_rect(src: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Rect Initializes ``r`` using the given ``src`` rectangle. This function will implicitly normalize the :obj:`~gi.repository.Graphene.Rect` before returning. .. versionadded:: 1.0 :param src: a :obj:`~gi.repository.Graphene.Rect` .. method:: inset(d_x: float, d_y: float) -> ~gi.repository.Graphene.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`` or ``d_y`` values; to create a larger, encompassing rectangle, use negative ``d_x`` or ``d_y`` values. The origin of the rectangle is offset by ``d_x`` and ``d_y``\, while the size is adjusted by ``(2 * @d_x, 2 * @d_y)``\. If ``d_x`` and ``d_y`` are positive values, the size of the rectangle is decreased; if ``d_x`` and ``d_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. .. versionadded:: 1.0 :param d_x: the horizontal inset :param d_y: the vertical inset .. method:: inset_r(d_x: float, d_y: float) -> ~gi.repository.Graphene.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`` or ``d_y`` values; to create a larger, encompassing rectangle, use negative ``d_x`` or ``d_y`` values. The origin of the rectangle is offset by ``d_x`` and ``d_y``\, while the size is adjusted by ``(2 * @d_x, 2 * @d_y)``\. If ``d_x`` and ``d_y`` are positive values, the size of the rectangle is decreased; if ``d_x`` and ``d_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. .. versionadded:: 1.4 :param d_x: the horizontal inset :param d_y: the vertical inset .. method:: interpolate(b: ~gi.repository.Graphene.Rect, factor: float) -> ~gi.repository.Graphene.Rect Linearly interpolates the origin and size of the two given rectangles. .. versionadded:: 1.0 :param b: a :obj:`~gi.repository.Graphene.Rect` :param factor: the linear interpolation factor .. method:: intersection(b: ~gi.repository.Graphene.Rect) -> ~typing.Tuple[bool, ~gi.repository.Graphene.Rect] Computes the intersection of the two given rectangles. .. image:: /rectangle-intersection.png 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. .. versionadded:: 1.0 :param b: a :obj:`~gi.repository.Graphene.Rect` .. method:: normalize() -> ~gi.repository.Graphene.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. .. versionadded:: 1.0 .. method:: normalize_r() -> ~gi.repository.Graphene.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. .. versionadded:: 1.4 .. method:: offset(d_x: float, d_y: float) -> ~gi.repository.Graphene.Rect Offsets the origin by ``d_x`` and ``d_y``\. The size of the rectangle is unchanged. .. versionadded:: 1.0 :param d_x: the horizontal offset :param d_y: the vertical offset .. method:: offset_r(d_x: float, d_y: float) -> ~gi.repository.Graphene.Rect Offsets the origin of the given rectangle by ``d_x`` and ``d_y``\. The size of the rectangle is left unchanged. .. versionadded:: 1.4 :param d_x: the horizontal offset :param d_y: the vertical offset .. method:: round() -> ~gi.repository.Graphene.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 :func:`~gi.repository.Graphene.Rect.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, and ``ceil`` on the size. .. versionadded:: 1.4 .. deprecated:: 1.10 Use :func:`~gi.repository.Graphene.Rect.round_extents` instead .. method:: round_extents() -> ~gi.repository.Graphene.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 calling ``ceil`` 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. .. versionadded:: 1.10 .. method:: round_to_pixel() -> ~gi.repository.Graphene.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. .. versionadded:: 1.0 .. deprecated:: 1.4 Use :func:`~gi.repository.Graphene.Rect.round` instead .. method:: scale(s_h: float, s_v: float) -> ~gi.repository.Graphene.Rect Scales the size and origin of a rectangle horizontaly by ``s_h``\, and vertically by ``s_v``\. The result ``res`` is normalized. .. versionadded:: 1.10 :param s_h: horizontal scale factor :param s_v: vertical scale factor .. method:: union(b: ~gi.repository.Graphene.Rect) -> ~gi.repository.Graphene.Rect Computes the union of the two given rectangles. .. image:: /rectangle-union.png The union in the image above is the blue outline. .. versionadded:: 1.0 :param b: a :obj:`~gi.repository.Graphene.Rect` .. classmethod:: zero() -> ~gi.repository.Graphene.Rect Returns a degenerate rectangle with origin fixed at (0, 0) and a size of 0, 0. .. versionadded:: 1.4 Fields ------ .. rst-class:: interim-class .. class:: Rect :no-index: .. attribute:: origin The coordinates of the origin of the rectangle .. attribute:: size The size of the rectangle