zPoint
============================================================================

	Summary	  Non-view class for handling points on a 2D coordinate system.

	Derived   None.

	Friends   There are several friend operators available to manipulate
              points and test two points for equality. They are all listed
              in the reference section below.

	Remarks   The zPoint object has two data members which are publicly
              accessible. They represent the column (x) and row (y)
              coordinates respectively. Note that no attempt is made to
              make any sense of the two values. The zPoint objects simply
              hold onto them and have no idea of their purpose.

	Notes     No error-checking is performed on the various parameters.
	          This is especially true for the operators that add or
	          subtract values. The caller must ensure that the values make
	          sense.


	ZPOINT::ZPOINT
	-----------------------------------------------------------------------

		Summary  Constructs a zPoint object in various ways.

		Syntax   zPoint();
		         zPoint(int aX, int aY);
		         zPoint(const zPoint &aPoint);

		Remarks  There are three ways to construct a zPoint object. The
                 first constructor will create a point with (0,0) as
                 position coordinates. The second one will create a point
                 with x = aX and y = aY. And finally, the third one is a
                 copy constructor which will create a point using the
                 values of the 'aPoint' parameter.

		Return   n/a

		Example  zPoint pt1;          // simple point (0,0)
		         zPoint pt2(10,15);   // point (10,15)
		         zPoint pt3(pt2);     // point is the same as pt2 (10,15)

	ZPOINT::X, ZPOINT::Y
	-----------------------------------------------------------------------

		Summary  The public data members for the column and row position.

		Syntax	 int x, y;

		Remarks  The 2D coordinate system used for the video display needs
                 two pieces of information to locate a point - a column
                 and row position. The convention in programming is to
                 assign 'x' to the column (horizontal) and 'y' to the row
                 (vertical) numbers. Note that zPoint objects can hold any
                 numbers (including invalid) in their data. It is the
                 responsibility of the caller to ensure that the values
                 are meaningful.

		Example  zPoint pt(10, 15);        // construct a point at (10,15)
		         int    px = pt.x;         // px = 10
		                pt.y += 2;         // pt is now at (10,17)


	ZPOINT::OPERATOR+=, ZPOINT::OPERATOR-=
	-----------------------------------------------------------------------

		Summary	 Operators used for adding or subtracting points.

		Syntax   void operator+=(const zPoint &adder);
		         void operator-=(const zPoint &subber);

		Remarks  Both operators modify the values in the calling point
                 object. The first one adds the x and y values of the
                 'adder' to the calling point, and the second one
                 subtracts the x and y values of the subber from the
                 calling point. Note that no error checking is performed
                 and it is quite possible to end up with negative values
                 for the data members.

		Return   Nothing.

		Example  zPoint point(10, 15);
		         zPoint adder(2, 4);
		         zPoint subber(3, 7);

                 point += adder;       // point is now at (12, 19)
                 point -= subber;      // point is now at (9, 12)


	OPERATOR-, OPERATOR+
	-----------------------------------------------------------------------

		Summary  Overloaded operators for adding and subtracting points.

		Syntax   zPoint operator+(const zPoint &pt1, const zPoint &pt2);
		         zPoint operator-(const zPoint &pt1, const zPoint &pt2);

		Remarks  These two friend operators construct new point objects
                 with data values from the two parameters. The first
                 operator will return a point whose data members are the
                 result of adding the 'pt1' and 'pt2' parameters, while
                 the second one will return a point whose data members are
                 the result of subtracting 'pt2' from 'pt1'. Note that
                 since a locally constructed object is returned, you
                 should not attempt to use its address.

		Return   zPoint object.

		Example  zPoint pt1(10, 12), pt2(3, 1), point;

                 point = pt1 + pt2;      // point is now at (13, 13)
                 point = pt1 - pt2;      // point is now at (7, 11)

	OPERATOR==, OPERATOR!=
	-----------------------------------------------------------------------

		Summary  Operators test two points for equality and inequality.

		Syntax   Boolean operator==(const zPoint &pt1, const zPoint &pt2);
		         Boolean operator!=(const zPoint &pt1, const zPoint &pt2);

		Remarks  These two friend operators test two points for equality.
                 The first one will return True only if both data members
                 of the 'pt1' and 'pt2' objects are equal, and False
                 otherwise. The second one will return True is either of
                 the data members in 'pt1' and 'pt2' is different from the
                 respective equivalent. It will return False otherwise.

		Return   operator== returns True if points are equal, False if not.
                 operator!= returns True if points are not equal, False if
                 they are.

		Example  zPoint pt1(10, 12), pt2(10, 11);

                 if( pt1 == pt2 )     // this is False
                 if( pt1 != pt2 )     // this is True


zRect
============================================================================

	Summary   A non-view class for specifying rectangles.

	Derived   None.

	Friends   There are two overloaded operators that determine the union
	          or intersection of two other rectangles and construct a new
	          one. These are described below, in the operator section.

	Remarks   This class contains member variables to define the top-left
              and bottom-right points of a rectangle. When specifying a
              rectangle, you must be careful to make it normalized (that
              is, the left coordinate is less than the right, and the top
              is less than the bottom). If a rectangle is not normalized,
              many of the member functions will return incorrect results.
              You can normalize a rectangle with the Normalize() member
              function.


	ZRECT::A, ZRECT::B
	------------------------------------------------------------------------

		Summary	 Members to represent the top-left and bottom-right values.

		Syntax	 zPoint a, b;

		Remarks  Both members are publicly accessible and can be modified
                 directly. Care must be taken that they are normalized
                 (i.e. a.x < b.x and a.y < b.y) or some member functions
                 may return incorrect results. You can use the Normalize()
                 function to do ensure the rectangle is normalized.

		Example  zRect rect;
                 int top  = rect.a.y;
                 int left = rect.a.x;

		See also zPoint, zPoint::zPoint


	ZRECT::ZRECT
	------------------------------------------------------------------------

		Summary  Construct a zRect object in various ways.

		Syntax   zRect();
		         zRect(int ax, int ay, int bx, int by);
		         zRect(const zPoint &topLeft, const zPoint &bottomRight);
		         zRect(const zRect &rect);

		Remarks  There four ways to construct a zRect object. The first
                 one will initialize the data members to 0. The second one
                 will use the 'ax' and 'ay' parameters to set the value
                 for the 'a' point, and 'bx' and 'by' to set the 'b' point
                 data member. The third constructor uses two points to
                 specify the top-left and bottom-right values for the
                 rectangle. The last one is a copy constructor which will
                 create a rectangle equal to the 'rect' parameter. You
                 must be careful to create a normalized rectangle because
                 some of the member functions will return incorrect
                 results if it is not (see the Remarks above).

		Example  zRect r1;             // all data members are set to 0
		         zRect r2(0,0,10,15);  // creates rectangle [(0,0),(10,15)]
		         zRect r3(zPoint(0,0), zPoint(10,15));  // same as above
		         zRect r4(r2);         // same as above

		See also zRect::Normalize


	ZRECT::CONTAINS
	------------------------------------------------------------------------

		Summary  Determines if a point lies within the rectangle.

		Syntax   Boolean contains(const zPoint &point) const;

		Remarks  This function determines if the 'point' lies within the
		         limits of the calling rectangle. The rectangle must be
		         normalized for this function to work. A point is considered
		         to be in the rectangle if its coordinates are greater than
		         or equal to left-top and less than bottom-right.

		Return   True if the point lies in the rectangle, False if not.

		Example  if( rect.contains(point) )		// do something

		See also zRect::empty


	ZRECT::EMPTY
	------------------------------------------------------------------------

		Summary	 Checks if the rectangle is empty.

		Syntax   Boolean empty() const;

		Remarks  A rectangle is considered empty if the top-left and bottom-
		         right values are the same or if the bottom-right position
		         if less than the top-left position. If the rectangle is
		         normalized, a True return value would mean that the two
		         bounding points are the same.

		Return   True if the rectangle is empty or non-normalized and
		         False otherwise.

		Example  // might fix a problem with non-normalized rectangles
                 if( rect.empty() ) rect.Normalize();

		See also zRect::Normalize


	ZRECT::HEIGHT
	------------------------------------------------------------------------

		Summary  Calculate the height (vertical extent) of the rectangle.

		Syntax   int Height() const;

		Remarks  This computes the vertical height of the rectangle by
		         simply subtracting the top-left from bottom-right. Note
		         that this function will return incorrect results for a
		         non-normalized rectangle.

		Return   The distance between the top and bottom rows. This might
		         be a negative number if rectangle is not normalized.

		Example  int h = rect.Height();

		See also zRect::Width, zRect::Size


	ZRECT::WIDTH
	------------------------------------------------------------------------

		Summary  Computes the width (horizontal extent) of the rectangle.

		Syntax   int Width() const;

		Remarks  This computes the horizontal extent of the rectangle by
		         simply subtracting the left from the right position. If
		         the rectangle is not normalized, the function will return
		         an incorrect result.

		Return	 The distance between the left and right columns. This
		         might be a negative number if rectangle is not normalized.

		Example  int width = rect.Width();

		See also zRect::Height, zRect::Size


	ZRECT::SIZE
	------------------------------------------------------------------------

		Summary  Computes the size of the rectangle in both extents.

		Syntax   zPoint Size() const;

		Remarks  Computes the extents (like width and height) of the
		         rectangle and returns a constructed zPoint object that
		         has the 'x' member set to the width and the 'y' member
		         set to the height of the rectangle. Since this object is
		         locally constructed within the function, you should not
		         attempt to preserve a pointer to it.

		Return   zPoint object with the extents of the rectangle.

		Example  zPoint size = rect.Size();

		See also zRect::Height, zRect::Size


	ZRECT::GROW
	------------------------------------------------------------------------

		Summary  Inflates or deflates the rectangle.

		Syntax   void grow(int dx, int dy);

		Remarks	 Depending of the delta values for x and y, this can cause
		         the rectangle to increase in size (inflate) or decrease
		         (deflate). You can use positive or negative numbers for
		         the function parameters. The size of the rectangle is
		         changed by subtracting 'dx' from left and adding it to
		         the right, and subtracting 'dy' from the top and adding
		         it to the bottom. Thus, negative values cause the rectangle
		         to shrink in size and positive values expand it. This
		         function has unpredictable (wrong) results if the calling
		         rectangle is not normalized. Also note that no error-
		         checking is performed and you might end up with negative
		         values in the data fields.

		Return   Nothing.

		Example  rect.grow(-1, -1);   // decrease size by 2 points

		See also zRect::move, zRect::operator+=, zRect::operator-=


	ZRECT::MOVE
	------------------------------------------------------------------------

		Summary  Moves the rectangle coordinates to new positions.

		Syntax   void move(int dx, int dy);

		Remarks  This routine moves the rectangle by adding the 'dx' value
		         to left and right, and adding the 'dy' delta value to top
		         and bottom. You can use negative numbers for the delta
		         parameters in which case the rectangle will move in the
		         opposite direction (left and up) instead of right and down.
		         Note that the rectangle must be normalized. No error checks
		         are performed, so you might end up with negative values for
		         the positions.

		Return   Nothing.

		Example  rect.move(-2, 4);   // move left 2 positions and down 4

		See also zRect::grow, zRect::operator+=, zRect::operator-=


	ZRECT::INTERSECT
	------------------------------------------------------------------------

		Summary  Makes rectangle as intersection of itself and another.

		Syntax   void Intersect(const zRect &rect);

		Remarks  Changes the calling rectangle to be the intersection of
		         itself and 'rect'. Both rectangles must be normalized for
		         this function to work. An intersection is defined as the
		         area that belongs to both rectangles (if they overlap) or
		         as the area between the two non-overlapping rectangles.

		Return   Nothing.

		Example  rect.Intersect(r2);  // adjust to fit intersection

		See also zRect::Union, zRect::operator&=, operator&


	ZRECT::UNION
	------------------------------------------------------------------------

		Summary  Makes rectangle as union of itself and another.

		Syntax   void Union(const zRect &rect);

		Remarks  Changes the calling rectangle to be the union of itself
		         and 'rect'. Both rectangles must be normalized or the
		         function will fail. A union is defined as the rectangle
		         that includes both other rectangles.

		Return   Nothing.

		Example  rect.Union(r2);   // adjust to include both rectangles

		See also zRect::Intersect, zRect::operator|=, operator|


	ZRECT::NORMALIZE
	------------------------------------------------------------------------

		Summary  Normalizes a rectangle so that bounding values are valid.

		Syntax   void Normalize();

		Remarks  A rectangle is normalized if top-left is smaller or equal
		         to the bottom-right position. This function will check the
		         current values and swap them if necessary. It will not
		         check for negative values as these can be quite valid in
		         the program context. It will just ensure that top-left is
		         smaller or equal to bottom-right.

		Return   Nothing.

		Example  rect.Normalize();   // make sure we're ok


	ZRECT::OPERATOR==
	------------------------------------------------------------------------

		Summary  Tests if two rectangles are equivalent.

		Syntax   Boolean operator==(const zRect &rect);

		Remarks  Checks if the calling rectangle is the same as the 'rect'
		         parameter. They will be the same if both the top-left and
		         bottom-right positions are the same.

		Return   True if the rectangles are the same, False if not.

		Example  if( rect1 == rect2 )   // do if they are the same

		See also zRect::operator!=


	ZRECT::OPERATOR!=
	------------------------------------------------------------------------

		Summary  Tests if two rectangles are different.

		Syntax   Boolean operator!=(const zRect &rect);

		Remarks  Checks if the calling rectangle is different from the
		         'rect' parameter. The rectangles will be different if
		         either top-left or bottom-right positions are not the
		         same in both of them.

		Return   True if the rectangles are different, False otherwise.

		Example  if( rect1 != rect2 )   // do if they are different

		See also zRect::operator==


	ZRECT::OPERATOR|=
	------------------------------------------------------------------------

		Summary  Makes rectangle the union of itself and another.

		Syntax   void operator|=(const zRect &rect);

		Remarks  This operator is equivalent to the zRect::Union member
		         function. It modifies the calling rectangle to be the
		         union of itself and the 'rect' parameter. Both rectangles
		         must be normalized for this operator to work. No error
		         checking is performed.

		Return   Nothing.

		Example  rect |= rect2;   // same as rect.Union(rect2);

		See also zRect::Union, zRect::operator&=, operator|


	ZRECT::OPERATOR&=
	------------------------------------------------------------------------

		Summary	 Makes rectangle an intersection of itself and another.

		Syntax   void operator&=(const zRect &rect);

		Remarks  This operator is equivalent to the zRect::Intersect member
		         function. It will modify the calling rectangle to be the
		         intersection of itself and the 'rect' parameter. Both
		         rectangles must be normalized for this routine to work.
		         No error-checking is performed.

		Return   Nothing.

		Example  rect &= rect2;    // same as rect.Intersect(rect2);

		See also zRect::Intersect, zRect::Union, operator&


	ZRECT::OPERATOR+=
	------------------------------------------------------------------------

		Summary	 Move or inflate the rectangle.

		Syntax   void operator+=(const zRect &rect);
		         void operator+=(const zPoint &delta);

		Remarks  This operator moves the calling rectangle. The first
		         version uses a 'rect' object to specify the values to
		         be added to each data member. Note that this may cause
		         the rectangle to change its dimensions depending on the
		         values of 'rect'. the second version uses a 'delta'
		         object of zPoint type to specify the values to be added
		         to each position respectively. This will only move the
		         rectangle and will not change its dimensions. You can
		         also specify negative values in the 'rect' and 'delta'
		         parameters to cause the originals to decrease.

		Return   Nothing.

		Example  rect += zPoint(1, 2);    // same as rect.move(1, 2);

		See also zRect::move, zRect::grow, zRect::operator-=


	ZRECT::OPERATOR-=
	------------------------------------------------------------------------

		Summary  Move or deflate the rectangle.

		Syntax   void operator-=(const zRect &rect);
		         void operator-=(const zPoint &delta);

		Remarks  The first operator will deflate the calling rectangle
		         by subtracting the values in 'rect' from the originals.
		         The second will move the rectangle by subtracting the
		         'delta' values from the originals. You can use negative
		         values in both 'rect' and 'delta' to cause inflation
		         or movement in the opposite direction.

		Return   Nothing.

		Example  rect -= zPoint(1, 3);    // same as rect.move(-1, -3);

		See also zRect::move, zRect::grow, zRect::operator+=


	OPERATOR&
	------------------------------------------------------------------------

		Summary  Creates a rectangle as intersection of other two.

		Syntax   zRect operator& (const zRect &r1, const zRect &r2);

		Remarks  This operator will create a new rectangle which will be
		         the intersection of the 'r1' and 'r2' parameters. If the
		         two rectangles overlap, the resulting one will be the
		         overlapping region. If they do not, the resulting one
		         will be the region between the two. Both rectangles must
		         be normalized for this operator to work properly. No
		         error checking is performed on the parameters. Since the
		         return value is a locally constructed zRect object, you
		         should not attempt to preserve a pointer to it. This
		         operator is a friend of the zRect class.

		Return   zRect object with the intersection region.

		Example  zRect ir = rect1 & rect2;  // ir is now the intersection

		See also zRect::Intersect, zRect::operator&=


	OPERATOR|
	------------------------------------------------------------------------

		Summary  Create a rectangle as a union of other two.

		Syntax   zRect operator| (const zRect &r1, const zRect &r2);

		Remarks  This operator creates a new rectangle which will be the
		         union of 'r1' and 'r2' parameters. The union is defined as
		         the rectangle which will include both of them. Both 'r1'
		         and 'r2' should be normalized for this operator to work.
		         No error checking is performed on the parameters. Since
		         the resulting object is constructed locally, the user
		         should not attempt to preserve a pointer to it.

		Return   zRect object which contains the union of the two rectangles.

		Example	 zRect ur = rect1 | rect2;   // ur is now the union

		See also zRect::Union, zRect::Intersection, zRect::operator|=

