<html> <head> <title>Developer's Guide: Rect Objects </title> </head> <body bgcolor=white text=black link=blue vlink=navy alink=red> <TABLE WIDTH="100%"> <TR> <TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH> <TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH> <TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH> </TR> <TR> <TD ALIGN="left"><A HREF="devguide-5.html">Point Objects </A></TD> <TD ALIGN="center"><A HREF="devguide-4.html">Coordinate Systems </A></TD> <TD ALIGN="right"><A HREF="devguide-7.html">Transformation Objects </A></TD> </TR> </TABLE> <HR NOSHADE> <H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Rect Objects </font></H2> <P>Rect objects, or rects for short, represent rectangular areas of the drawing whose edges are parallel to the coordinate axes. They are represented by four floats for the positions of the left, bottom, right and top edges. Rects are kept in a normalized state where the left coordinate a less than the right coordinate and the bottom coordinate less than the top coordinate.</P> <P>The <A HREF="devguide-12.html">bounding rects and coord rects</A> of the graphics objects are such rect objects.</P> <P>Rect objects provide efficient methods for boolean operations (union and intersection of rects) and tests for overlapping rects and contained points.</P> <P>There are two special rect objects: <CODE>InfinityRect</CODE> and <CODE>EmptyRect</CODE>. <CODE>InfinityRect</CODE> represents the entire 2D plane while <CODE>EmptyRect</CODE> is an empty rect. These objects behave in special ways: both overlap every other rect, <CODE>InfinityRect</CODE> contains all points while <CODE>EmptyRect</CODE> contains no point, and so on. The particular coordinates of these objects are irrelevant.</P> <P>Rect objects are immutable.</P> <P>Note: these rect objects have nothing to do with the rectangle primitive (apart from the fact that the rectangle primitive has a bounding box...).</P> <H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Constructors</font></H3> <P> <DL> <DT><B><A NAME="N3"></A><tt>Rect(<i>left</i>, <i>bottom</i>, <i>right</i>, <i>top</i>)</tt></B><DD> <DT><B><A NAME="N4"></A><tt>Rect(<i>llcorner</i>, <i>urcorner</i>)</tt></B><DD> <P>Return a new Rect object with the coordinates <i>left</i>, <i>bottom</i>, <i>right</i> and <i>top</i> or the opposite corners <i>llcorner</i> and <i>urcorner</i> given as <A HREF="devguide-5.html">points objects</A>. The rectangle is automatically normalized, so you can swap <i>left</i>/<i>right</i> or <i>top</i>/<i>bottom</i> or choose any opposite corners.</P> <DT><B><A NAME="N5"></A><tt>PointsToRect(<i>sequence</i>)</tt></B><DD> <P>Return the smallest rect that contains all points in <i>sequence</i>. <i>sequence</i> must be a sequence of <A HREF="devguide-5.html#N11">PointSpecs</A>. If <i>sequence</i> is empty return <CODE>EmptyRect</CODE></P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N6"></A>Attributes</font></H3> <P>A rect object has four (read only) attributes: <DL> <DT><B><CODE>left</CODE></B><DD> <DT><B><CODE>bottom</CODE></B><DD> <DT><B><CODE>right</CODE></B><DD> <DT><B><CODE>top</CODE></B><DD> <P>The left, bottom, right and top coordinate of the rect as python floats. For <CODE>InfinityRect</CODE> and <CODE>EmptyRect</CODE> these have no real meaning.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N7"></A>Methods</font></H3> <P>A rect object has these methods (self refers to the rect whose method is called):</P> <P> <DL> <DT><B><CODE>contains_point(<i>PointSpec</i>)</CODE></B><DD> <DT><B><CODE>contains_point(<i>x</i>, <i>y</i>)</CODE></B><DD> <P>Return true, if the point given by <i>PointSpec</i> or <i>x</i> and <i>y</i> is inside of self, false otherwise.</P> <P>For <CODE>InfinityRect</CODE> this is always true, for <CODE>EmptyRect</CODE> always false.</P> <DT><B><CODE>contains_rect(<i>r</i>)</CODE></B><DD> <P>Return true, if the rect <i>r</i> lies completely inside of self. A rect contains itself. </P> <P><CODE>InfinityRect</CODE> contains all other rects and <CODE>EmptyRect</CODE> is contained in all other rects. </P> <DT><B><CODE>overlaps(<i>r</i>)</CODE></B><DD> <P>Return true if self and the rect <i>r</i> overlap. A rect overlaps itself.</P> <P><CODE>InfinityRect</CODE> and <CODE>EmptyRect</CODE> overlap all other rects and each other.</P> <DT><B><CODE>translated(<i>PointSpec</i>)</CODE></B><DD> <DT><B><CODE>translated(<i>x</i>, <i>y</i>)</CODE></B><DD> <P>Return self translated by the vector <i>PointSpec</i> or <i>x</i> and <i>y</i>. Equivalent to</P> <P>Rect(self.left + x, self.bottom + y, self.right + x, self.top + y)</P> <P>For <CODE>InfinityRect</CODE> and <CODE>EmptyRect</CODE>, return self.</P> <DT><B><CODE>grown(<i>amount</i>)</CODE></B><DD> <P>Return a rect that is larger than self by <i>amount</i> in every direction. Equivalent to</P> <P><CODE>Rect(self.left - amount, self.bottom - amount, self.right + amount, self.top + amount)</CODE></P> <P>For <CODE>InfinityRect</CODE> and <CODE>EmptyRect</CODE>, return self.</P> <DT><B><CODE>center()</CODE></B><DD> <P>Return the center point of self as a point object.</P> <P>For <CODE>InfinityRect</CODE> and <CODE>EmptyRect</CODE>, return <CODE>Point(0, 0)</CODE>.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N8"></A>Operators</font></H3> <P>Rect objects implement the sequence protocol for Python objects. This allows the following operations: <DL> <DT><B><CODE>len(<i>rect</i>)</CODE></B><DD> <P>Always returns 4.</P> <DT><B><CODE><i>rect</i>[<i>i</i>]</CODE></B><DD> <P>If <CODE><i>i</i></CODE> is one of 0, 1, 2 or 3, this is the same as <CODE><i>rect</i>.left</CODE> <CODE><i>rect</i>.bottom</CODE>, <CODE><i>rect</i>.right</CODE> or <CODE><i>rect</i>.top</CODE> respectively.</P> <P>For other values of <i>i</i> raise an IndexError exception.</P> <DT><B><CODE>tuple(<i>rect</i>)</CODE></B><DD> <P>Return the coordinates of <i>rect</i> as a tuple</P> <P><CODE>(<i>rect</i>.left, <i>rect</i>.bottom, <i>rect</i>.right, <i>rect</i>.top)</CODE>.</P> <DT><B><CODE>left, bottom, right, top = <i>rect</i></CODE></B><DD> <P>Unpack the rect <CODE><i>rect</i></CODE>. Equivalent to</P> <P><CODE>left, bottom, right, top = tuple(<i>rect</i>)</CODE></P> </DL> </P> <P><CODE>rect</CODE> is a rect object, <CODE>len</CODE> is the builtin function.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N9"></A>Functions</font></H3> <P> <DL> <DT><B><A NAME="N10"></A><tt>UnionRects(<i>rect1</i>, <i>rect2</i>)</tt></B><DD> <P>Return the union of the rects <i>rect1</i> and <i>rect2</i>. The union is the smallest rect containing both rects.</P> <P>If one the arguments is <CODE>InfinityRect</CODE> return <CODE>InfinityRect</CODE>, if one of the arguments is <CODE>EmptyRect</CODE> return the other argument.</P> <DT><B><A NAME="N11"></A><tt>IntersectRects(<i>rect1</i>, <i>rect2</i>)</tt></B><DD> <P>Return the intersection of the rects <i>rect1</i> and <i>rect2</i>. The intersection is the largest rect contained in both rects.</P> <P>If one the arguments is <CODE>EmptyRect</CODE> return <CODE>EmptyRect</CODE>, if one of the arguments is <CODE>InfinityRect</CODE> return the other argument.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N12"></A>Constants</font></H3> <P> <DL> <DT><B><CODE>InfinityRect</CODE></B><DD> <P>Represents the entire 2D plane.</P> <DT><B><CODE>EmptyRect</CODE></B><DD> <P>The empty rect.</P> <DT><B><CODE>UnitRect</CODE></B><DD> <P><CODE>Rect(0, 0, 1, 1)</CODE></P> <DT><B><CODE>RectType</CODE></B><DD> <P>The rect type object.</P> </DL> </P> <HR NOSHADE> <TABLE WIDTH="100%"> <TR> <TD ALIGN="left"><A HREF="devguide-5.html">Point Objects </A></TD> <TD ALIGN="center"><A HREF="devguide-4.html">Coordinate Systems </A></TD> <TD ALIGN="right"><A HREF="devguide-7.html">Transformation Objects </A></TD> </TR> <TR> <TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH> <TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH> <TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH> </TR> </TABLE> </body> </html>
