<html>
<head>
<title>Developer's Guide: The class Bounded
</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-11.html">The class GraphicsObject</A></TD>
<TD ALIGN="center"><A HREF="devguide-9.html">The Document and Graphics Classes</A></TD>
<TD ALIGN="right"><A HREF="devguide-13.html">The class HierarchyNode
</A></TD>
</TR>
</TABLE>
<HR NOSHADE>
<H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>The class <A NAME="N2"></A><tt>Bounded</tt>
</font></H2>
<P>In Sketch, each graphics object has a <EM>bounding rectangle</EM> and a
<EM>coordinate rectangle</EM>. The sides of both rectangles are parallel to
the coordinate axes.</P>
<P>The bounding rectangle is a rectangle that contains the entire object.
Any marks the object or its children leave on the paper when printed lie
in it. Ideally it should be the smallest such rectangle, but in practice
it is sometimes difficult and indeed not always desirable to get exactly
the smallest one. In any case, the bounding rectangle must contain the
entire object.</P>
<P>Sketch uses the bounding rect for three purposes: to decide, which parts
of the screen to redraw, as an aid when deciding which objects to select
and to compute the BoundingBox of an EPS-File.</P>
<P>The coordinate rectangle is the smallest rectangle that contains the
entire object without taking the line width into account. Sketch uses
this rectangle for layout purposes and as the reference for interactive
resize- and transformation operations.</P>
<P>The coordinate rectangle of an object should always lie completely
inside of the bounding rectangle. Both rectangles may be (and for many
object types they are) identical.</P>
<P>Since <tt>Bounded</tt>'s variables are used for layout calculations, it
provides access to and default behavior for the <EM>layout point</EM>. The
layout point is the point of an object that should lie exactly on the
grid or on other special points.</P>
<P>By default, the layout point is the lower left corner of the coordinate
rectangle. For images this is the lower left corner of the image which
is not identical to the default if the image was transformed. For text
objects with default justification, the layout point is the origin of
the first letter, which is on the baseline, whereas the coordinate
rectangle takes the descender into account.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N3"></A>Instance Variables</font></H3>
<P><tt>Bounded</tt> provides the following instance variables</P>
<P>
<DL>
<DT><B><CODE>bounding_rect</CODE>:</B><DD>
<P>the bounding rectangle</P>
<DT><B><CODE>coord_rect</CODE>:</B><DD>
<P>the coordinate rectangle</P>
</DL>
</P>
<P>These instance variables are public attributes. Sketch uses
<CODE>bounding_rect</CODE> to speed up the search for the object a mouse click
has hit (when the point the user clicked on is outside of the bounding
rect, the object cannot be hit). This test is significantly faster when
the bounding rectangle is read directly from an attribute instead of
accessed through a method call.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N4"></A>Methods</font></H3>
<P><tt>Bounded</tt> implements lazy evaluation for its public instance
variables (<CODE>bounding_rect</CODE> and <CODE>coord_rect</CODE>). When one of these
variables is not defined, <tt>Bounded</tt>'s <A HREF="#N7"><tt>__getattr__</tt></A>
method invokes the method <A HREF="#N6"><tt>update_rects</tt></A> to compute the
rectangles and set the variables. To force recomputation when these
variables are read next, a derived class may call <A HREF="#N5"><tt>del_lazy_attrs</tt></A>.</P>
<P>This lazy evaluation mechanism is not limited to the instance variables
mentioned above. <tt>__getattr__</tt> consults the dictionary
<CODE>self._lazy_attrs</CODE> to determine, whether the requested attribute is a
lazy attribute: if <CODE>self._lazy_attrs</CODE> has the attribute as a key the
attribute is treated as a lazy attribute. The value associated with that
key must be the name of the method to call to recompute the value of the
attribute. <tt>__getattr__</tt> calls this method and expects that
<CODE>self</CODE> has that attribute after the method has run.</P>
<P><CODE>_lazy_attrs</CODE> is a class variable of <tt>Bounded</tt>. If a derived
class needs additional lazy attributes, it should create its own class
variable <CODE>_lazy_attrs</CODE> as a copy of its base-class' <CODE>_lazy_attrs</CODE>
and add the appropriate keys: </P>
<P>
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
class MyObject(GraphicsObject):
_lazy_attrs = GraphicsObject._lazy_attrs.copy()
_lazy_attrs['my_lazy_attribute'] = 'update_my_lazy_attr'
# somewhere in the class definition:
def update_my_lazy_attr(self):
# compute the new value of my_lazy_attr...
# ... and finally:
self.my_lazy_attribute = new_value
</PRE>
</td></tr></table>
</P>
<P>Thus <tt>Bounded</tt>'s methods are:
<DL>
<DT><B><A NAME="N5"></A><tt>del_lazy_attrs()</tt></B><DD>
<P>Delete the `lazy' instance variables. Any attempt to access a
lazy attribute later triggers its recomputation via the
<tt>__getattr__</tt> method.</P>
<DT><B><A NAME="N6"></A><tt>update_rects()</tt></B><DD>
<P><CODE>Bounded.__getattr__</CODE> invokes this method whenever one of the
attributes <CODE>bounding_rect</CODE> or <CODE>coord_rect</CODE> is not set.</P>
<P>This method <EM>must</EM> be supplied by some derived class and it
<EM>must</EM> compute both rectangles.</P>
<DT><B><A NAME="N7"></A><tt>__getattr__(<i>attr</i>)</tt></B><DD>
<P>If <CODE>self._lazy_attrs.has_key(attr)</CODE> is true, invoke
<CODE>getattr(self, self._lazy_attrs[attr])()</CODE> to recompute the
attribute.</P>
<DT><B><A NAME="N8"></A><tt>LayoutPoint()</tt></B><DD>
<P>Return the layout point of self as a <A HREF="devguide-5.html">point object</A>. Default is the lower left corner
of <CODE>self.coord_rect</CODE>.</P>
<DT><B><A NAME="N9"></A><tt>GetSnapPoints()</tt></B><DD>
<P>Return a list of <A HREF="devguide-5.html">point objects</A>
indicating the `hot spots' of the graphics object. These points
are used when `Snapping to Objects' is active. The default
implementation returns an empty list.</P>
</DL>
</P>
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"><A HREF="devguide-11.html">The class GraphicsObject</A></TD>
<TD ALIGN="center"><A HREF="devguide-9.html">The Document and Graphics Classes</A></TD>
<TD ALIGN="right"><A HREF="devguide-13.html">The class HierarchyNode
</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>
