source: trunk/docs/api/zoo-bounds.txt @ 779

.. _api-zoo-bounds:

ZOO.Bounds
==========

Instances of this class represent bounding boxes.

Properties      
----------

.. list-table::
   :widths: 30 50
   :header-rows: 1

   * - NAME
     - DESCRIPTION
   * - :ref:`left <left>`
     - {Number} Minimum horizontal coordinate.
   * - :ref:`bottom <bottom>`
     - {Number} Minimum vertical coordinate. 
   * - :ref:`right <right>` 
     - {Number} Maximum horizontal coordinate.
   * - :ref:`top <top>`
     - {Number} Maximum vertical coordinate.   
     
Functions
---------  

.. list-table::
   :widths: 20 50
   :header-rows: 1

   * - NAME
     - DESCRIPTION
   * - :ref:`ZOO.Bounds <ZOO.Bounds>`
     - Construct a new bounds object.
   * - :ref:`clone <clone>`
     - Create a cloned instance of this bounds.
   * - :ref:`equals <equals>` 
     - Test a two bounds for equivalence.
   * - :ref:`toString <toString>`
     - {String} String representation of bounds object.
   * - :ref:`toBBOX <toBBOX>`
     - 
   * - :ref:`toGeometry <toGeometry>`
     - Create a new polygon geometry based on this bounds.
   * - :ref:`getWidth <getWidth>` 
     - {Float} The width of the bounds
   * - :ref:`getHeight <getHeight>`
     - {Float} The height of the bounds (top minus bottom)  
   * - :ref:`add <add>`
     - 
   * - :ref:`extend <extend>`
     - Extend the bounds to include the point, lonlat, or bounds specified.
   * - :ref:`intersectsBounds <intersectsBounds>` 
     - Determine whether the target bounds intersects this bounds.
   * - :ref:`containsBounds <containsBounds>`
     - Determine whether the target bounds is contained within this bounds.     

**Properties**
   
.. _left:   
   
left    
  ``{Number}`` Minimum horizontal coordinate.
  
.. _bottom:     
  
bottom  
  ``{Number}`` Minimum vertical coordinate.

.. _right:     

right   
  ``{Number}`` Maximum horizontal coordinate.

.. _top:     

top     
  ``{Number}`` Maximum vertical coordinate.

**Functions**

.. _ZOO.Bounds:     

ZOO.Bounds      
  Construct a new bounds object.
  
  *Parameters*

  | ``left {Number}`` The left bounds of the box.  Note that for width calculations, this is assumed to be less than the right value.
  | ``bottom {Number}`` The bottom bounds of the box.  Note that for height calculations, this is assumed to be more than the top value.
  | ``right {Number}`` The right bounds.
  | ``top {Number}`` The top bounds.  
  
.. _clone:       

clone   
  ::
  
    clone:function()

  Create a cloned instance of this bounds.

  *Returns*

  :ref:`{ZOO.Bounds} <api-zoo-bounds>` A fresh copy of the bounds

.. _equals:       

equals  
  ::
  
    equals:function(bounds)

  Test a two bounds for equivalence.

  *Parameters*
  
  | ``bounds {ZOO.Bounds}``
  
  *Returns*

  ``{Boolean}`` The passed-in bounds object has the same left, right, top, bottom components as this.  Note 
  that if bounds passed in is null, returns false.

.. _toString: 

toString        
  :: 
  
    toString:function()

  *Returns*

  ``{String}`` String representation of bounds object.  (ex. *<i>"left-bottom=(5,42) right-top=(10,45)"</i>*)
  
.. _toBBOX:   
  
toBBOX  
  ::
  
    toBBOX:function(decimal)

  *Parameters*
  
  ``decimal {Integer}`` How many significant digits in the bbox coords?  Default is 6

  *Returns*

  ``{String}`` Simple String representation of bounds object.  (ex. *<i>"5,42,10,45"</i>*)  

.. _toGeometry:   

toGeometry      
  ::
  
    toGeometry: function()

  Create a new polygon geometry based on this bounds.

  *Returns*

  :ref:`{ZOO.Geometry.Polygon} <api-zoo-geometry-polygon>` A new polygon with the coordinates of this bounds.
  
.. _getWidth:     

getWidth        
  ::    
  
    getWidth:function()

  *Returns*

  ``{Float}`` The width of the bounds
  
.. _getHeight:       
  
getHeight       
  ::
  
    getHeight:function()

  *Returns*

  ``{Float}`` The height of the bounds (top minus bottom).

.. _add:       

add
  ::
  
    add:function(x,y)

  *Parameters*

  | ``x {Float}``
  | ``y {Float}``

  *Returns*

  :ref:`{ZOO.Bounds} <api-zoo-bounds>` A new bounds whose coordinates are the same as this, but shifted by the passed-in x and y values.

.. _extend:       

extend  
  ::
  
    extend:function(object)

  Extend the bounds to include the point, lonlat, or bounds specified.  Note, this function assumes that left 
  < right and bottom < top.
  
  *Parameters*
  
  ``object {Object}`` Can be Point, or Bounds.
  
.. _intersectsBounds:         
  
intersectsBounds        
  ::
  
    intersectsBounds:function(bounds,inclusive)

  Determine whether the target bounds intersects this bounds.  Bounds are considered intersecting if any 
  of their edges intersect or if one bounds contains the other.

  *Parameters*
  
  | ``bounds`` :ref:`{ZOO.Bounds} <api-zoo-bounds>` The target bounds.
  | ``inclusive {Boolean}`` Treat coincident borders as intersecting.  Default is true.  If false, bounds that do not overlap but only touch at the border will not be considered as intersecting.

  *Returns*

  ``{Boolean}`` The passed-in bounds object intersects this bounds.
 
.. _containsBounds:          
 
containsBounds  
  ::
  
    containsBounds:function(bounds,partial,inclusive)

  Determine whether the target bounds is contained within this bounds.

  *Parameters*
  
  | ``bounds`` :ref:`{ZOO.Bounds} <api-zoo-bounds>` The target bounds.
  | ``partial {Boolean}`` If any of the target corners is within this bounds consider the bounds contained.  Default is false.  If true, the entire target bounds must be contained within this bounds.
  | ``inclusive {Boolean}`` Treat shared edges as contained.  Default is true.

  *Returns*

  ``{Boolean}`` The passed-in bounds object is contained within this bounds.