Mercurial > pygame
annotate src/rect.doc @ 1849:301bc61643a9 math_module
merged changes from trunk
| author | lorenz |
|---|---|
| date | Mon, 16 Nov 2009 18:31:40 +0000 |
| parents | 02c1e8e9c102 |
| children |
| rev | line source |
|---|---|
| 627 | 1 pygame.Rect |
| 2 pygame object for storing rectangular coordinates | |
| 3 pygame.Rect(left, top, width, height): return Rect | |
| 4 pygame.Rect((left, top), (width, height)): return Rect | |
| 5 pygame.Rect(object): return Rect | |
| 6 | |
| 7 Pygame uses Rect objects to store and manipulate rectangular areas. A Rect | |
| 8 can be created from a combination of left, top, width, and height values. | |
| 9 Rects can also be created from python objects that are already a Rect or | |
| 10 have an attribute named "rect". | |
| 11 | |
| 629 | 12 Any Pygame function that requires a Rect argument also accepts any of |
| 627 | 13 these values to construct a Rect. This makes it easier to create Rects |
| 14 on the fly as arguments to functions. | |
| 15 | |
| 16 The Rect functions that change the position or size of a Rect return | |
|
696
cc66586f274d
some changes from doc comments on website.
Rene Dudfield <renesd@gmail.com>
parents:
629
diff
changeset
|
17 a new copy of the Rect with the affected changes. The original Rect |
| 627 | 18 is not modified. Some methods have an alternate "in-place" version that |
| 19 returns None but effects the original Rect. These "in-place" methods | |
| 629 | 20 are denoted with the "ip" suffix. |
| 627 | 21 |
| 22 The Rect object has several virtual attributes which can be used to move | |
| 629 | 23 and align the Rect: |
| 627 | 24 |
| 25 top, left, bottom, right | |
| 26 topleft, bottomleft, topright, bottomright | |
| 27 midtop, midleft, midbottom, midright | |
| 28 center, centerx, centery | |
| 29 size, width, height | |
|
768
800c092ebf0b
added w and h attributes which were not in docs
Rene Dudfield <renesd@gmail.com>
parents:
696
diff
changeset
|
30 w,h |
| 627 | 31 |
| 629 | 32 All of these attributes can be assigned to: |
| 33 | |
| 34 rect1.right = 10 | |
| 35 rect2.center = (20,30) | |
| 36 | |
| 37 Assigning to size, width or height changes the dimensions of the | |
| 38 rectangle; all other assignments move the rectangle without | |
| 39 resizing it. Notice that some attributes are integers and | |
| 40 others are pairs of integers. | |
| 41 | |
| 627 | 42 If a Rect has a nonzero width or height, it will return True for a |
| 43 nonzero test. Some methods return a Rect with 0 size to represent an | |
| 44 invalid rectangle. | |
| 45 | |
| 46 The coordinates for Rect objects are all integers. The size values | |
| 47 can be programmed to have negative values, but these are considered | |
| 48 illegal Rects for most operations. | |
| 49 | |
| 629 | 50 There are several collision tests between other rectangles. Most |
| 627 | 51 python containers can be searched for collisions against a single Rect. |
| 52 | |
| 629 | 53 The area covered by a Rect does not include the right- and bottom-most |
| 54 edge of pixels. If one Rect's bottom border is another Rect's top border | |
| 55 (i.e., rect1.bottom=rect2.top), the two meet exactly on the screen | |
| 56 but do not overlap, and rect1.colliderect(rect2) returns false. | |
|
1506
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
57 |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
58 Though Rect can be subclassed, methods that return new rectangles are not |
| 1839 | 59 subclass aware. That is, move or copy return a new pygame.Rect instance, |
|
1506
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
60 not an instance of the subclass. This may change. To make subclass awareness |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
61 work though, subclasses may have to maintain the same constructor signature |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
62 as Rect. |
| 627 | 63 <SECTION> |
| 64 | |
| 65 | |
|
1506
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
66 copy |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
67 copy the rectangle |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
68 Rect.copy(): return Rect |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
69 |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
70 Returns a new rectangle having the same position and size as the orginal. |
| 1849 | 71 |
| 72 New in pygame 1.9 | |
|
1506
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
73 <END> |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
74 |
|
a60459a910fd
Bugzilla feature request 25: add Rect.copy method
Lenard Lindstrom <len-l@telus.net>
parents:
1038
diff
changeset
|
75 |
| 627 | 76 move |
| 77 moves the rectangle | |
| 78 Rect.move(x, y): return Rect | |
| 79 | |
| 80 Returns a new rectangle that is moved by the given offset. The x and y | |
| 81 arguments can be any integer value, positive or negative. | |
| 82 <END> | |
| 83 | |
| 84 | |
| 85 | |
| 86 move_ip | |
| 87 moves the rectangle, in place | |
| 88 Rect.move_ip(x, y): return None | |
| 89 | |
| 90 Same as the Rect.move() method, but operates in place. | |
| 91 <END> | |
| 92 | |
| 93 | |
| 94 inflate | |
| 95 grow or shrink the rectangle size | |
| 96 Rect.inflate(x, y): return Rect | |
| 97 | |
| 98 Returns a new rectangle with the size changed by the given offset. The | |
| 99 rectangle remains centered around its current center. Negative values | |
| 100 will shrink the rectangle. | |
| 101 <END> | |
| 102 | |
| 103 | |
| 104 inflate_ip | |
| 105 grow or shrink the rectangle size, in place | |
| 106 Rect.inflate_ip(x, y): return None | |
| 107 | |
| 108 Same as the Rect.inflate() method, but operates in place. | |
| 109 <END> | |
| 110 | |
| 111 | |
| 112 | |
| 113 clamp | |
| 114 moves the rectangle inside another | |
| 115 Rect.clamp(Rect): return Rect | |
| 116 | |
| 117 Returns a new rectangle that is moved to be completely inside the argument | |
| 118 Rect. If the rectangle is too large to fit inside, it is centered inside | |
| 629 | 119 the argument Rect, but its size is not changed. |
| 627 | 120 <END> |
| 121 | |
| 122 | |
| 123 | |
| 124 clamp_ip | |
| 125 moves the rectangle inside another, in place | |
| 126 Rect.clamp_ip(Rect): return None | |
| 127 | |
| 128 Same as the Rect.clamp() method, but operates in place. | |
| 129 <END> | |
| 130 | |
| 131 | |
| 132 | |
| 133 clip | |
| 134 crops a rectangle inside another | |
| 135 Rect.clip(Rect): return Rect | |
| 136 | |
| 137 Returns a new rectangle that is cropped to be completely inside the | |
| 138 argument Rect. If the two rectangles do not overlap to begin with, a | |
| 139 Rect with 0 size is returned. | |
| 140 <END> | |
| 141 | |
| 142 | |
| 143 union | |
| 144 joins two rectangles into one | |
| 145 Rect.union(Rect): return Rect | |
| 146 | |
| 147 Returns a new rectangle that completely covers the area of the two | |
| 629 | 148 provided rectangles. There may be area inside the new Rect that is |
| 149 not covered by the originals. | |
| 627 | 150 <END> |
| 151 | |
| 152 | |
| 153 | |
| 154 union_ip | |
| 155 joins two rectangles into one, in place | |
| 156 Rect.union_ip(Rect): return None | |
| 157 | |
| 158 Same as the Rect.union() method, but operates in place. | |
| 159 <END> | |
| 160 | |
| 161 | |
| 162 | |
| 163 unionall | |
| 164 the union of many rectangles | |
| 165 Rect.unionall(Rect_sequence): return Rect | |
| 166 | |
| 167 Returns the union of one rectangle with a sequence of many rectangles. | |
| 168 <END> | |
| 169 | |
| 170 | |
| 171 | |
| 172 unionall_ip | |
| 173 the union of many rectangles, in place | |
| 174 Rect.unionall_ip(Rect_sequence): return None | |
| 175 | |
| 176 The same as the Rect.unionall() method, but operates in place. | |
| 177 <END> | |
| 178 | |
| 179 | |
| 180 | |
| 181 fit | |
| 182 resize and move a rectangle with aspect ratio | |
| 183 Rect.fit(Rect): return Rect | |
| 184 | |
| 185 Returns a new rectangle that is moved and resized to fit another. The | |
| 186 aspect ratio of the original Rect is preserved, so the new rectangle may | |
| 187 be smaller than the target in either width or height. | |
| 188 <END> | |
| 189 | |
| 190 | |
| 191 | |
| 192 normalize | |
| 193 correct negative sizes | |
| 194 Rect.normalize(): return None | |
| 195 | |
| 196 This will flip the width or height of a rectangle if it has a negative | |
| 197 size. The rectangle will remain in the same place, with only the sides | |
| 198 swapped. | |
| 199 <END> | |
| 200 | |
| 201 | |
| 202 | |
| 203 contains | |
| 204 test if one rectangle is inside another | |
| 205 Rect.contains(Rect): return bool | |
| 206 | |
| 629 | 207 Returns true when the argument is completely inside the Rect. |
| 627 | 208 <END> |
| 209 | |
| 210 | |
| 211 | |
| 212 collidepoint | |
| 629 | 213 test if a point is inside a rectangle |
| 627 | 214 Rect.collidepoint(x, y): return bool |
|
769
2bdbe4cd99f9
collidepoint can also take a tupple
Rene Dudfield <renesd@gmail.com>
parents:
768
diff
changeset
|
215 Rect.collidepoint((x,y)): return bool |
| 627 | 216 |
| 217 Returns true if the given point is inside the rectangle. A point along | |
| 218 the right or bottom edge is not considered to be inside the rectangle. | |
| 219 <END> | |
| 220 | |
| 221 | |
| 222 | |
| 223 colliderect | |
| 224 test if two rectangles overlap | |
| 225 Rect.colliderect(Rect): return bool | |
| 226 | |
| 629 | 227 Returns true if any portion of either rectangle overlap (except |
| 228 the top+bottom or left+right edges). | |
| 627 | 229 <END> |
| 230 | |
| 231 | |
| 232 | |
| 233 collidelist | |
| 234 test if one rectangle in a list intersects | |
| 235 Rect.collidelist(list): return index | |
| 236 | |
| 629 | 237 Test whether the rectangle collides with any in a sequence of rectangles. |
| 627 | 238 The index of the first collision found is returned. If no collisions are |
| 239 found an index of -1 is returned. | |
| 240 <END> | |
| 241 | |
| 242 | |
| 243 | |
| 244 collidelistall | |
| 245 test if all rectangles in a list intersect | |
| 246 Rect.collidelistall(list): return indices | |
| 247 | |
| 248 Returns a list of all the indices that contain rectangles that collide | |
| 629 | 249 with the Rect. If no intersecting rectangles are found, an empty list |
| 627 | 250 is returned. |
| 251 <END> | |
| 252 | |
| 253 | |
| 254 | |
| 255 collidedict | |
| 256 test if one rectangle in a dictionary intersects | |
| 257 Rect.collidedict(dict): return (key, value) | |
| 258 | |
| 259 Returns the key and value of the first dictionary value that collides | |
| 260 with the Rect. If no collisions are found, None is returned. | |
| 261 | |
| 262 Rect objects are not hashable and cannot be used as keys in a dictionary, | |
| 263 only as values. | |
| 264 <END> | |
| 265 | |
| 266 | |
| 267 | |
| 268 collidedictall | |
| 269 test if all rectangles in a dictionary intersect | |
| 270 Rect.collidedictall(dict): return [(key, value), ...] | |
| 271 | |
| 272 Returns a list of all the key and value pairs that intersect with the | |
| 273 Rect. If no collisions are found an empty dictionary is returned. | |
| 274 | |
| 275 Rect objects are not hashable and cannot be used as keys in a dictionary, | |
| 276 only as values. | |
| 277 <END> | |
| 278 <END> |