sdl2.ext.rect - rectangular object.

A rectangular object for storing and manipulating coordinates.

Note

This is a MODIFIED, pure Python implementation of PyGameSDL2’s rect,
in Cython, released under zlib license.
PygameSDL2 Notice / zlib License:

--------------------------------------------------------------------------
Original work:
  Copyright 2014 Tom Rothamel <tom@rothamel.us>
  Copyright 2014 Patrick Dawson <pat@dw.is>
Modified work:
  Copyright 2017 Lucas Siqueira <lucas.morais.siqueira@gmail.com>

This software is provided 'as-is', without any express or implied
warranty.  In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would be
   appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not
   be misrepresented as being the original software.
3. This notice may not be removed or altered from any source
   distribution.
--------------------------------------------------------------------------
class sdl2.ext.rect.IterableRect

Bases: sdl2.ext.rect.RectAbstract

class sdl2.ext.rect.NonIterableRect(*args)

Bases: sdl2.ext.rect.RectAbstract

Object for storing rectangular coordinates.

__init__(*args)

Initialization.

Rect objects are used to store and manipulate rectangular areas. A Rect can be created from a combination of left, top, width, and height values. Rects can also be created from python objects that are already a Rect or have an attribute named rect.

The Rect functions that change the position or size of a Rect return a new copy of the Rect with the affected changes. The original Rect is not modified. Some methods have an alternate in-place version that returns None but effects the original Rect. These in-place methods are denoted with the ip suffix.

The Rect object has several virtual attributes which can be used to move and align the Rect: >>> x,y >>> top, left, bottom, right >>> topleft, bottomleft, topright, bottomright >>> midtop, midleft, midbottom, midright >>> center, centerx, centery >>> size, width, height >>> w,h

All of these attributes can be assigned to: >>> rect1.right = 10 >>> rect2.center = (20,30)

Assigning to size, width or height changes the dimensions of the rectangle; all other assignments move the rectangle without resizing it. Notice that some attributes are integers and others are pairs of integers.

If a Rect has a nonzero width or height, it will return True for a nonzero test. Some methods return a Rect with 0 size to represent an invalid rectangle.

The coordinates for Rect objects are all integers. The size values can be programmed to have negative values, but these are considered illegal Rects for most operations.

There are several collision tests between other rectangles. Most python containers can be searched for collisions against a single Rect.

The area covered by a Rect does not include the right- and bottom- most edge of pixels. If one Rect’s bottom border is another Rect’s top border (i.e., rect1.bottom=rect2.top), the two meet exactly on the screen but do not overlap, and rect1.colliderect(rect2) returns false.

The Rect class can be subclassed. Methods such as copy() and move() will recognize this and return instances of the subclass. However, the subclass’s __init__() method is not called, and __new__() is assumed to take no arguments. So these methods should be overridden if any extra attributes need to be copied.

Args.:
(4 int tuple; e.g. (left, top, width, height)); or (2 int tuple, i.e. one tuple for x and y coordinates, another for dimensions; e.g. “(left, top), (width, height)”); or (Rect, i.e. another Rect to be copied).
Raises:TypeError
Usage:
Rect(left, top, width, height) -> Rect Rect((left, top), (width, height)) -> Rect Rect(object) -> Rect
bottom

...

bottomleft

...

bottomright

...

center

...

centerx

...

centery

...

clamp(other)

Move the rectangle inside another.

Returns a new rectangle that is moved to be completely inside the argument Rect. If the rectangle is too large to fit inside, it is centered inside the argument Rect, but its size is not changed.

Usage:
source_rect.clamp(Rect)
Returns:Rect (a new Rect instance)
clamp_ip(other)

Move the rectangle inside another.

The rectangle is moved to be completely inside the argument Rect, operating in place. If the rectangle is too large to fit inside, it is centered inside the argument Rect, but its size is not changed.

Usage:
rect.clamp(Rect)
Returns:None
clip(other, y=None, w=None, h=None)

Crop a rectangle inside another.

Returns a new rectangle that is cropped to be completely inside the argument Rect. If the two rectangles do not overlap to begin with, a Rect with 0 size is returned.

Usage:
clip(Rect)
Returns:Rect (a new Rect instance)
collidedict(other_dict)

Test if one rectangle in a dictionary intersects.

Returns the key and value of the first dictionary value that collides with the Rect. If no collisions are found, None is returned.

Rect objects are not hashable and cannot be used as keys in a dictionary, only as values.

Usage:
collidedict(dict)
Returns:tuple (key and value of first rect in the dictionary that
collides)
None (if no collision is detected)
collidedictall(other_dict, rects_values=0)

Test if one rectangle instersect with others in a dictionary.

Returns a list of tuples with the key and value of the rectangles in the argument dictionary that intersect with the Rect. If no collisions are found an empty list is returned.

Rect objects are not hashable and cannot be used as keys in a dictionary, only as values.

Usage:
collidedictall(dict)
Returns:list of tuples ([(key, value), ...] with the rectangles that collide) empty list (if none collide)
collidelist(other_list)

Test if the rectangle collide with any rectangle in the list.

Test whether the rectangle collides with any in a sequence of rectangles. The index of the first collision found is returned. If no collisions are found an index of -1 is returned.

Usage:
rect.collidelist(list)
Returns:int (index of first rectangle that collides or -1 none collides)
collidelistall(other_list)

Test if all rectangles in a list intersect.

Returns a list of all the indices that contain rectangles that collide with the Rect. If no intersecting rectangles are found, an empty list is returned.

Usage:
rect.collidelistall(list)
Returns:list (i.e. indices of rectangles that collide)
collidepoint(x, y)

Test if a point is inside a rectangle.

Returns True if the given point is inside the rectangle. A point along the right or bottom edge is not considered to be inside the rectangle.

Parameters:
  • x (int) – X (horizontal) coordinate of the point
  • y (int) – Y (vertical) coordinate of the point
Usage:
rect.collidepoint(0, 3) rect.collidepoint(x=0, y=3)
Returns:bool
colliderect(other)

Test if two rectangles overlap.

Returns true if any portion of either rectangle overlap (except the top+bottom or left+right edges).

Usage:
rect.colliderect(Rect)
Returns:bool
contains(other)

Test if an argument rectangle is inside the rectangle.

Returns true when the argument is completely inside the Rect.

Usage:
rect.contains(Rect)
Returns:bool
copy()

Copy the rectangle.

Returns a new rectangle having the same position and size as the original.

Usage:
source_rect.copy()
Returns:Rect (a new Rect instance)
fit(other)

Resize and move a rectangle with aspect ratio.

Returns a new rectangle that is moved and resized to fit another. The aspect ratio of the original Rect is preserved, so the new rectangle may be smaller than the target in either width or height.

Usage:
source_rect.fit(Rect)
Returns:Rect (a new Rect instance)
gap(other)

Return a new rectangle representing the gap between two rectangles.

If the two rectangles overlap a Rect with size 0 is returned.

height

...

inflate(*args)

Grow or Shrink the rectangle size.

Usage:
source_rect.inflate(x, y)
Returns:Rect (a new Rect instance)

Returns a new rectangle with the size changed by the given offset. The rectangle remains centered around its current center. Negative values will shrink the rectangle.

inflate_ip(*args)

Grow or shrink the rectangle size, in place.

The rectangle’s size is changed by the given offset, operating in place. Negative values will shrink the rectangle.

Usage:
rect.inflate(x, y)
Returns:None
left

...

midbottom

...

midleft

...

midright

...

midtop

...

move(*args)

Move the rectangle.

Returns a new rectangle that is moved by the given offset. The x and y arguments can be any integer value, positive or negative.

Usage:
source_rect.move(x, y)
Returns:Rect (a new Rect instance)
move_ip(*args)

Move the rectangle, in place.

The rectangle is moved by the given offset, operating in place. The x and y arguments can be any integer value, positive or negative.

Usage:
rect.move(x, y)
Returns:None
normalize()

Correct negative sizes of the rectangle.

This will flip the width or height of a rectangle if it has a negative size. The rectangle will remain in the same place, with only the sides swapped.

Usage:
rect.normalize()
Returns:None
right

...

size

...

top

...

topleft

...

topright

...

union(other)

Join two rectangles into one.

Returns a new rectangle that completely covers the area of the two provided rectangles. There may be area inside the new Rect that is not covered by the originals.

Usage:
source_rect.union(Rect)
Returns:Rect (a new Rect instance)
union_ip(other)

Join two rectangles into one.

The rectangle is resized to completely cover its original area and that of the argument Rect, operating in place. The resized Rect may contain areas that were not covered by either the original Rect or the argument Rect.

Usage:
source_rect.union(Rect)
Returns:None
unionall(other_seq)

Join many rectangles into a new one.

Returns the union of one rectangle with a sequence of many rectangles.

Usage:
source_rect.unionall(Rect_sequence)
Returns:Rect (a new Rect instance)
unionall_ip(other_seq)

Join many rectangles into one.

The rectangle is resized to cover its original area and that of the passed as argument, operating in place.

Usage:
rect.unionall(Rect_sequence)
Returns:None
width

...

class sdl2.ext.rect.Rect(*args)

Bases: sdl2.ext.rect.NonIterableRect, sdl2.ext.rect.IterableRect

class sdl2.ext.rect.RectAbstract

Bases: object

sdl2.ext.rect.flatten(*args)

...

sdl2.ext.rect.to_sdl_rect(rl)

Convert rectlike to the SDL_Rect rect.

Parameters:rl (tuple, Rect) – a rectlike object (either a Rect or a 4-tuple representing of representing x, y, w and h.
Returns:class:sdl2.rect.SDL_Rect

Examples

>>> rl1 = Rect(1, 2, 10, 20)
>>> r1 = to_sdl_rect(rl)
>>> rl2 = (1, 2, 10, 20)
>>> r2 = to_sdl_rect(rl)
>>> assert r1 == r2