Class RubberBandBox

This class encapuslates the information for drawing and tracking a "rubber band box" drawn to show selected areas on the map. There are actually four layers of boxes that can be displayed, and all are tied together. If you wanted to have multiple selections with different "endpoints", you would have to create multiple RubberBandBox objects. The class assumes that it is attached to a MapCanvas object (or an object derived from MapCanvas) in some of it's calls.
The four layers of bounding boxes are:
  • XY Box (green)
    • This box represent the actual x/y coordinates on the screen (relative to the canvas). In terms of geospatial selection, this one isn't very useful, but can be useful for things which require "image coordinates", such as zooms. By default, this box is displayed.
    The box passed to XYListeners is an object containing four fields:
  • x0 - The x coordinate of the upper left corner
  • y0 - The y coordinate of the upper left corner
  • x1 - The x coordinate of the lower right corner
  • y1 - The y coordinate of the lower right corner

    • Thus, an XYListener should accept one parameter. For example:
    function myXYListener(box)...
    // (info can be found using box.x0, etc)
  • Spherical Rectangle (yellow)
    • This box represents the same box as the XY Box, but mapped to geo- spatial coordinates. The corners of the rectangle will be the same as the XY box, but the sides of the rectangle will be curves that represent the Great Circles that connect these corners. This type of box is useful especially over the poles, where a latitude/longitude box would not work. By default, this box is NOT displayed.
    The box passed to LatLonPolygonListeners is an array of points, in counter-clockwise order, where each point is one of the corners. There are 5 points, as the last point will be equivalent to the first point to create an explicitely-closed polygon. Each point is an object containing two fields:
  • lat - The latitude corresponding to the point
  • lon - The longitude corresponding to the point.

    • Thus, a LatLonPolygonListener should accept one parameter, an array. For example:
    function myLLPListener(box)...
    // (info can be found using box[0].lat, box[2].lon, etc)
    // (note that box[0] will equal box[4])
  • Latitude/Longitude Box (red)
    • This box represents a box bounded by upper and lower latitudes and longitudes. Unlike the Spherical Rectangle, only two of the corners will align with the XY Box corners, specifically the "start" corner and the "end" corner (the corners where the drawing of the box starts and ends). The box is then drawn by using the lat/lon values of these two corners, and using the values to create the other two corners. For instance, if the "start" values are (50.0, 30.0), and the "end" values are (70.0, 80.0), the other two corners will be (50.0, 80.0) and (70.0, 30.0).
    On cylindrical projections, this box will appear rectangular, and will exactly overlap the XY Box. On other projections the edges may be curved. For example, in polar stereographic projections, the lat/lon box will appear to be arc-shaped.
    By default, this box is NOT displayed.
    The box passed to LatLonListeners is an object containing four fields:
  • west - The westernmost longitude of the box
  • east - The easternmost longitude of the box
  • north - The northernmost latitude of the box
  • south - The southernmost latitude of the box

    • Thus, a LatLonListener should accept one parameter, an object. For example:
    function myLatLonListener(box)...
    // (info can be found using box.west, etc)
  • Row/Column Box (white)
    • This box represents the selection of descrete "gridpoints" in a grid. For very fine grids, the selection will appear exactly the same as the XY grid, except the coordinates will be in grid coordinates rather than image coordinates. For very coarse grids, this selection may appear a bit larger, as the selection works for discrete grid coordinates, not partial coordinates (ie, integers only). This can be useful, for instance, when selecting on maps that have underlying "tile data", and you want a selection of the tiles returned. Currently, individual grid cells cannot be selected; they can only be selected as part of a rectangle. For very fine grids, this may not be as useful, unless you want the grid coordinates for the corner points, rather than the x/y coordinates.
    Unlike the other layers, this layer does not draw a "boundary" of the selection, but rather just a uniform, translucent box.
    By default, this box is NOT displayed.
    The box passed to RowColListeners is an object containing four fields:
  • ul - the upper left corner
  • ur - the upper right corner
  • ll - the lower left corner
  • lr - the lower right corner

    • Each of these fields is actually an object also, with the following fields:
  • row - the integer row of the corner
  • col - the integer column of the corner
  • fullrow - the EXACT row of the corner, including partial
  • fullcol - the EXACT column of the corner, including partial

    • fullrow and fullcol don't themselves directly map to the white selection, but rather they represent the row/col coordinates that correspond with the GREEN box; in other words, the exact row/col coordinates, rather than the "tiled"/integerized version.
    Thus, a RowColListeners should accept one parameter, an object. For example:
    function myRowColListener(box)...
    // (info can be found using box.ul.row, box.lr.fullcol, etc)

    Constructor Summary

    RubberBandBox ( newCanvas , newParent )
    Creates a new RubberBandBox object and initializes it.

    Method Summary

    addXYListener ( newListener )
    Attaches a lister to receive XY Box information
    getXYInfo ( )
    Manually retrieves the current information for the XY Box
    addLatLonListener ( newListener )
    Attaches a listener to receive Lat/Lon information
    addLatLonPolygonListener ( newListener )
    Attaches a listener to receive Lat/Lon Polygon (spherical rectangle) info
    addRowColListener ( newListener )
    Attaches a listener to receive Row/Col information
    setShowXY ( newShow )
    Shows or hides the XY Box
    setShowLatLon ( newShow )
    Shows or hides the LatLon Box
    setShowSphRect ( newShow )
    Shows or hides the Spherical Rectangle Box
    setShowRowCol ( newShow )
    Shows or hides the Row/Col Box
    startDrag ( x , y )
    Signals the object that a new box is being created
    moveDrag ( x , y )
    Indicates that the current drag position has moved
    endDrag ( x , y )
    Indicates that the current drag has ended, and the box is complete
    setXYFromLatLonPolygon ( polygon )
    Resets the XYBox values (and thus, all other values from there) to match as closely as possible the input polygon.
    adjustLatLon ( param , newValue )
    Adjusts manually the latitude/longitude bounds of the LatLon box, and updates all the other boxes accordingly.
    refresh ( )
    Resets the coordinates of the boxes
    draw ( )
    Draws all the visible boxes

    Constructor Detail

    RubberBandBox
    Creates a new RubberBandBox object and initializes it.


    Parameters
    newCanvas - A reference to a drawing canvas
    newParent - A reference to an object that contains the RBB


    Returns
    a new RubberBandBox object

    Examples 
    var rbb = new RubberBandBox(drawCanvas, this);
    // called within a MapCanvas object, this will create a new
    // RubberBandBox object.  drawCanvas should be a dojo drawing
    // surface, which the base MapCanvas object will set up.  The
    // "this" refers to the MapCanvas object creating the RBB.

    Notes
    You will very seldom need to create an RBB object manually, even when creating child MapCanvas classes, as the base MapCanvas class will create this for you. The newCanvas parameter is necessary as it tells the RubberBandBox where to draw the various boxes. The newParent parameter is vital in that many of the methods to return box information use the projection information in the parent MapCanvas object to convert to the right coordinate set.

    Method Detail

    addXYListener
    Attaches a lister to receive XY Box information


    Parameters
    newListener - the listener that will receive the info

    Returns
    None.

    Examples 
    rbb.addXYListener(myXYListener);
    // Attaches myXYListener to the object

    Notes
    When a box has been fully created (ie, started, dragged, and let go), all XY Listeners will be called by being passed an object described in the box information in the class header above.

    getXYInfo
    Manually retrieves the current information for the XY Box


    Parameters
    None.

    Returns
    An object containing the XY box.

    Examples 
    var box = rbb.getXYInfo();
    // Gets the information for the XY box

    Notes
    Sometimes you may need to get the XY box without having a listener for it (such as with some zoom functions, for example). This allows you to manually retrieve the information in the XY Box. Note that if there is no current XY box drawn, the information returned may be undefined.

    addLatLonListener
    Attaches a listener to receive Lat/Lon information


    Parameters
    newListener - the listener that will receive the info

    Returns
    None.

    Examples 
    rbb.addLatLonListener(myLatLonListener);
    // Attaches the listener for the Lat/Lon box

    Notes
    When a box has been fully created (ie, started, dragged, and let go), all Lat/Lon listeners will be called by being passed an object described in the box information in the class header above.

    addLatLonPolygonListener
    Attaches a listener to receive Lat/Lon Polygon (spherical rectangle) info


    Parameters
    newListener - the listener that will receive the info

    Returns
    None.

    Examples 
    rbb.addLatLonPolygonListener(myLLPListener);
    // Attaches the listener for the Lat/Lon Polygon box

    Notes
    When a box has been fully created (ie, started, dragged, and let go), all Lat/Lon listeners will be called by being passed an array described in the box information in the class header above.

    addRowColListener
    Attaches a listener to receive Row/Col information


    Parameters
    newListener - the listener that will receive the info

    Returns
    None.

    Examples 
    rbb.addRowColListener(myRCListener);
    // Attaches the listener for the Row/Col box

    Notes
    When a box has been fully created (ie, started, dragged, and let go), all Row/Col listeners will be called by being passed an object described in the box information in the class header above.

    setShowXY
    Shows or hides the XY Box


    Parameters
    newShow - A boolean indicating whether to show the XY Box

    Returns
    None.

    Examples 
    rbb.setShowXY(true);    // displays the XY Box
    rbb.setShowXY(false);   // hides the XY Box

    Notes
    By default, the XY Box is shown. Also, displaying the box has no impact over whether listeners will get information; ie, even if the box is hidden, all XYListeners will still be called with the correct XY information.

    setShowLatLon
    Shows or hides the LatLon Box


    Parameters
    newShow - A boolean indicating whether to show the Lat/Lon Box

    Returns
    None.

    Examples 
    rbb.setShowLatLon(true);    // displays the Lat/Lon Box
    rbb.setShowLatLon(false);   // hides the Lat/Lon Box

    Notes
    By default, the Lat/Lon Box is hidden. Also, displaying the box has no impact over whether listeners will get information; ie, even if the box is hidden, all LatLonListeners will still be called with the correct Lat/Lon information.

    setShowSphRect
    Shows or hides the Spherical Rectangle Box


    Parameters
    newShow - A boolean indicating whether to show the Box

    Returns
    None.

    Examples 
    rbb.setShowSphRect(true);    // displays the Box
    rbb.setShowSphRect(false);   // hides the Box

    Notes
    By default, the Spherical Rectangle Box is hidden. Also, displaying the box has no impact over whether listeners will get information; ie, even if the box is hidden, all LatLonPolygonListeners will still be called with the correct information.

    setShowRowCol
    Shows or hides the Row/Col Box


    Parameters
    newShow - A boolean indicating whether to show the Row/Col Box

    Returns
    None.

    Examples 
    rbb.setShowRow/Col(true);    // displays the Row/Col Box
    rbb.setShowRow/Col(false);   // hides the Row/Col Box

    Notes
    By default, the Row/Col Box is shown. Also, displaying the box has no impact over whether listeners will get information; ie, even if the box is hidden, all RowColListeners will still be called with the correct Row/Col information.

    startDrag
    Signals the object that a new box is being created


    Parameters
    x - The image x coordinate the drag is being started at
    y - The image y coordinate the drag is being started at

    Returns
    None.

    Examples 
    rbb.startDrag(100,100);
    // signals that a new box is being created starting at point
    // (100,100)

    Notes
    You should probably not have to ever call this manually. This is public due to scoping issues in JavaScript, but is called by the MapCanvas object.

    moveDrag
    Indicates that the current drag position has moved


    Parameters
    x - The current x coordinate for the drag
    y - The current y coordinate for the drag

    Returns
    None.

    Examples 
    rbb.moveDrag(150,150);
    // indicates that the current drag position is at (150,150)

    Notes
    You should probably not have to ever call this manually. This is public due to scoping issues in JavaScript, but is called by the MapCanvas object. The non-hidden boxes will be drawn after each call to this method.

    endDrag
    Indicates that the current drag has ended, and the box is complete


    Parameters
    x - The x coordinate where the drag ended
    y - The y coordinate where the drag ended

    Returns
    None.

    Examples 
    rbb.endDrag(175,175);
    // indicates that the drag was ended (mouseup) at (175,175)

    Notes
    You should probably not have to ever call this manuall. This is public due to scoping issues in JavaScript, but is called by the MapCanvas object. The non-hidden boxes will be drawn after each call to this method, and all box listeners will be called with the appropriate box information.

    setXYFromLatLonPolygon
    Resets the XYBox values (and thus, all other values from there) to match as closely as possible the input polygon.


    Parameters
    polygon - A string or an array representing the polygon

    Returns
    None. (The boxes will be redrawn, however)

    Examples 
    rbb.setXYFromLatLonPolygon("50,50,50,100,100,100,100,50,50,50");
    // string form
    rbb.setXYFromLatLonPolygon(50,50,50,100,100,100,100,50,50,50);
    // array of integers form
    rbb.setXYFromLatLonPolygon(pt1, pt2, pt3, pt4, pt1);
    // array of Points form

    Notes
    The input value can be a string, or one of two types of array. A string should be in "lt0,ln0,lt1,ln1,lt2,ln2,lt3,ln3,lt0,ln0" format. (lt is latitude, ln is longitude). An array of integers should be in the same order as a string, but sent as an array of floating points instead. An array of points should be in pt0,pt1,pt2,pt3,pt0 order, where each point has both lat and lon properties. If the input does not meet these requirements, the boxes will not be altered.

    adjustLatLon
    Adjusts manually the latitude/longitude bounds of the LatLon box, and updates all the other boxes accordingly.


    Parameters
    param - "north", "south", "west", or "east"; the parameter to adjust
    newValue - The new latitude/longitude value of the parameter

    Returns
    None. (The boxes will be redrawn, however)

    Examples 
    rbb.adjustLatLon("north", 65.5);
    // adjusts the North parameter to 65.5N
    rbb.adjustLatLon("west", -120.3);
    // adjusts the West parameter to 120.3W

    Notes
    If a value not listed above is used for param, the method returns with no effect. The newValue is converted to be within global parameters (-90/90 for latitude, -180/180 for longitude). If the value pushes it so it's beyond the "opposite" boundary, the values are swapped; ie, if a new North value is farther south than the current South value, the new value will be the new South value, and the previous South value will be the new North value. Finally, all other boxes will be recalculated to match this one; note that the XY "touching corners" may be changed. All listeners are called to receive new box information.

    refresh
    Resets the coordinates of the boxes


    Parameters
    None.

    Returns
    None.

    Examples 
    rbb.refresh(); // resets the X/Y and Lat/Lon boxes

    Notes
    After calling this, the boxes will be "erased" from the screen, though they are not "hidden" in that they will appear when a new box is created without having to call one of the setShowxxx methods. You should only rarely have to call this manually, though, as MapCanvas will handle this.

    draw
    Draws all the visible boxes


    Parameters
    None.

    Returns
    None.

    Examples 
    rbb.draw();  // draws all the visible boxes

    Notes
    You sould never need to call this manually, as MapCanvas and the various RubberBandBox methods will call this when appropriate. It is public only due to the way scoping works in JavaScript