Changeset 184

Show
Ignore:
Timestamp:
03/20/07 21:24:14 (2 years ago)
Author:
migurski
Message:

Added copious comments in As2Doc style

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/as2/lib/com/modestmaps/Map.as

    r179 r184  
    11/* 
    22 * vim:et sts=4 sw=4 cindent: 
    3  * $Id$ 
     3 * @ignore 
     4 * 
     5 * @author Michal Migurski <mike@stamen.com> 
     6 * @author Darren David <darren@lookorfeel.com> 
     7 * 
     8 * com.modestmaps.Map is the base class and interface for Modest Maps. 
     9 * 
     10 * Correctly attaching an instance of this MovieClip subclass should result 
     11 * in a pannable map. Controls and event handlers must be added separately. 
     12 * 
     13 * @usage <code> 
     14 *          import com.modestmaps.Map; 
     15 *          import com.modestmaps.geo.Location; 
     16 *          import com.modestmaps.mapproviders.BlueMarbleMapProvider; 
     17 *          import com.stamen.twisted.Reactor; 
     18 *          ... 
     19 *          Reactor.run(clip, null, 50); 
     20 *          var map:Map = Map(clip.attachMovie(Map.symbolName, 'map', clip.getNextHighestDepth())); 
     21 *          map.init(640, 480, true, new BlueMarbleMapProvider()); 
     22 *        </code> 
    423 */ 
    524 
    …… 
    3049 
    3150    // frames-per-2x-zoom 
    32     private static var __zoomFrames:Number = 6; 
     51    public var zoomFrames:Number = 6; 
    3352     
    3453    // frames-per-full-pan 
    35     private static var __panFrames:Number = 12; 
     54    public var panFrames:Number = 12; 
    3655     
    3756    private var __startingPosition:Point; 
    …… 
    6382   /* 
    6483    * Initialize the map: set properties, add a tile grid, draw it. 
     84    * Default extent covers the entire globe, (+/-85, +/-180). 
     85    * 
     86    * @param    Width of map, in pixels. 
     87    * @param    Height of map, in pixels. 
     88    * @param    Whether the map can be dragged or not. 
     89    * @param    Desired map provider, e.g. Blue Marble. 
     90    * 
     91    * @see com.modestmaps.core.TileGrid 
    6592    */ 
    6693    public function init(width:Number, height:Number, draggable:Boolean, provider:IMapProvider):Void 
    …… 
    94121    * bounds using calculateMapExtent(), and inform the grid of 
    95122    * tile coordinate and point by calling grid.resetTiles(). 
     123    * Resulting map extent will ensure that all passed locations 
     124    * are visible. 
     125    * 
     126    * @param    Array of locations. 
     127    * 
     128    * @see com.modestmaps.Map#calculateMapExtent 
     129    * @see com.modestmaps.core.TileGrid#resetTiles 
    96130    */ 
    97131    public function setExtent(locations:/*Location*/Array):Void 
    …… 
    107141    * tile coordinate and point using calculateMapCenter(), and inform 
    108142    * the grid of tile coordinate and point by calling grid.resetTiles(). 
     143    * 
     144    * @param    Location of center. 
     145    * @param    Desired zoom level. 
     146    * 
     147    * @see com.modestmaps.Map#calculateMapExtent 
     148    * @see com.modestmaps.core.TileGrid#resetTiles 
    109149    */ 
    110150    public function setCenterZoom(location:Location, zoom:Number):Void 
    …… 
    191231   /* 
    192232    * Return the current coverage area of the map, as four locations. 
     233    * 
     234    * @return   Array of four locations: [top-left, top-right, bottom-left, bottom-right]. 
    193235    */ 
    194236    public function getExtent():/*Location*/Array 
    …… 
    220262 
    221263   /* 
    222     * Return the current center location and zoom of the map, in a two-element array. 
     264    * Return the current center location and zoom of the map. 
     265    * 
     266    * @return   Array of center and zoom: [center location, zoom number]. 
    223267    */ 
    224268    public function getCenterZoom():Array 
    …… 
    228272 
    229273   /** 
    230     * Set new map size. 
     274    * Set new map size, call onResized(). 
     275    * 
     276    * @param    New map width. 
     277    * @param    New map height. 
     278    * 
     279    * @see com.modestmaps.Map#onResized 
    231280    */ 
    232281    public function setSize(width:Number, height:Number):Void 
    …… 
    239288 
    240289   /** 
    241     * Get map size, width:Number, height:Number. 
     290    * Get map size. 
     291    * 
     292    * @return   Array of [width, height]. 
    242293    */ 
    243294    public function getSize():/*Number*/Array 
    …… 
    248299 
    249300   /** 
    250     * Get a reference to the current mapProvider. 
     301    * Get a reference to the current map provider. 
     302    * 
     303    * @return   Map provider. 
     304    * 
     305    * @see com.modestmaps.mapproviders.IMapProvider 
    251306    */ 
    252307    public function getMapProvider():IMapProvider 
    …… 
    256311 
    257312   /** 
    258     * Set a new mapProvider, repainting tiles and changing bounding box if necessary. 
     313    * Set a new map provider, repainting tiles and changing bounding box if necessary. 
     314    * 
     315    * @param   Map provider. 
     316    * 
     317    * @see com.modestmaps.mapproviders.IMapProvider 
    259318    */ 
    260319    public function setMapProvider(newProvider:IMapProvider):Void 
    …… 
    276335   /** 
    277336    * Get a point (x, y) for a location (lat, lon) in the context of a given clip. 
     337    * 
     338    * @param    Location to match. 
     339    * @param    Movie clip context in which returned point should make sense. 
     340    * 
     341    * @return   Matching point. 
    278342    */ 
    279343    public function locationPoint(location:Location, context:MovieClip):Point 
    …… 
    285349   /** 
    286350    * Get a location (lat, lon) for a point (x, y) in the context of a given clip. 
     351    * 
     352    * @param    Point to match. 
     353    * @param    Movie clip context in which passed point should make sense. 
     354    * 
     355    * @return   Matching location. 
    287356    */ 
    288357    public function pointLocation(point:Point, context:MovieClip):Location 
    …… 
    294363   /** 
    295364    * Pan up by 2/3 of the map height. 
     365    * @see com.modestmaps.Map#panMap 
    296366    */ 
    297367    public function panUp():Void 
    298368    { 
    299369        var distance:Number = -2*__height / 3; 
    300         panMap(new Point(0, Math.round(distance/__panFrames))); 
     370        panMap(new Point(0, Math.round(distance/panFrames))); 
    301371    }       
    302372 
    303373   /** 
    304374    * Pan down by 2/3 of the map height. 
     375    * @see com.modestmaps.Map#panMap 
    305376    */ 
    306377    public function panDown():Void 
    307378    { 
    308379        var distance:Number = 2*__height / 3; 
    309         panMap(new Point(0, Math.round(distance/__panFrames))); 
     380        panMap(new Point(0, Math.round(distance/panFrames))); 
    310381    } 
    311382     
    312383   /** 
    313384    * Pan to the left by 2/3 of the map width. 
     385    * @see com.modestmaps.Map#panMap 
    314386    */ 
    315387    public function panLeft():Void 
    316388    { 
    317389        var distance:Number = -2*__width / 3; 
    318         panMap(new Point(Math.round(distance/__panFrames, 0))); 
     390        panMap(new Point(Math.round(distance/panFrames, 0))); 
    319391    }       
    320392 
    321393   /** 
    322394    * Pan to the right by 2/3 of the map width. 
     395    * @see com.modestmaps.Map#panMap 
    323396    */ 
    324397    public function panRight():Void 
    325398    { 
    326399        var distance:Number = 2*__width / 3; 
    327         panMap(new Point(Math.round(distance/__panFrames, 0))); 
     400        panMap(new Point(Math.round(distance/panFrames, 0))); 
    328401    } 
    329402     
    330403    private function panMap(perFrame:Point):Void 
    331404    { 
    332         for(var i = 1; i <= __panFrames; i += 1) 
     405        for(var i = 1; i <= panFrames; i += 1) 
    333406            __animSteps.push({type: 'pan', amount: perFrame}); 
    334407             
    …… 
    343416     
    344417   /** 
    345     * Zoom in by 200% over the course of __zoomFrames frames. 
     418    * Zoom in by 200% over the course of several frames. 
     419    * @see com.modestmaps.Map#zoomFrames 
    346420    */ 
    347421    public function zoomIn():Void 
    348422    { 
    349         for(var i = 1; i <= __zoomFrames; i += 1) 
    350             __animSteps.push({type: 'zoom', amount: 1/__zoomFrames, redraw: Boolean(i == __zoomFrames)}); 
     423        for(var i = 1; i <= zoomFrames; i += 1) 
     424            __animSteps.push({type: 'zoom', amount: 1/zoomFrames, redraw: Boolean(i == zoomFrames)}); 
    351425             
    352426        if(!__animTask) { 
    …… 
    360434     
    361435   /** 
    362     * Zoom in by 200% over the course of __zoomFrames frames. 
     436    * Zoom out by 50% over the course of several frames. 
     437    * @see com.modestmaps.Map#zoomFrames 
    363438    */ 
    364439    public function zoomOut():Void 
    365440    { 
    366         for(var i = 1; i <= __zoomFrames; i += 1) 
    367             __animSteps.push({type: 'zoom', amount: -1/__zoomFrames, redraw: Boolean(i == __zoomFrames)}); 
     441        for(var i = 1; i <= zoomFrames; i += 1) 
     442            __animSteps.push({type: 'zoom', amount: -1/zoomFrames, redraw: Boolean(i == zoomFrames)}); 
    368443             
    369444        if(!__animTask) { 
    …… 
    425500   /** 
    426501    * Add a marker with the given id and location (lat, lon). 
     502    * 
     503    * @param    ID of marker, opaque string. 
     504    * @param    Location of marker. 
    427505    */ 
    428506    public function putMarker(id:String, location:Location):Void 
    …… 
    434512   /** 
    435513    * Remove a marker with the given id. 
     514    * 
     515    * @param    ID of marker, opaque string. 
    436516    */ 
    437517    public function removeMarker(id:String):Void 
    …… 
    443523    * Dispatches EVENT_MARKER_ENTERS when a given marker enters the tile coverage area. 
    444524    * Event object includes id:String and location:Location. 
     525    * 
     526    * @param    ID of marker. 
     527    * @param    Location of marker. 
     528    * 
     529    * @see com.modestmaps.Map#EVENT_MARKER_ENTERS 
    445530    */ 
    446531    public function onMarkerEnters(id:String, location:Location):Void 
    …… 
    453538    * Dispatches EVENT_MARKER_LEAVES when a given marker leaves the tile coverage area. 
    454539    * Event object includes id:String and location:Location. 
     540    * 
     541    * @param    ID of marker. 
     542    * @param    Location of marker. 
     543    * 
     544    * @see com.modestmaps.Map#EVENT_MARKER_LEAVES 
    455545    */ 
    456546    public function onMarkerLeaves(id:String, location:Location):Void 
    …… 
    463553    * Dispatches EVENT_START_ZOOMING when the map starts zooming. 
    464554    * Event object includes level:Number. 
     555    * 
     556    * @see com.modestmaps.Map#EVENT_START_ZOOMING 
    465557    */ 
    466558    public function onStartZoom():Void 
    …… 
    473565    * Dispatches EVENT_STOP_ZOOMING when the map stops zooming. 
    474566    * Callback arguments includes level:Number. 
     567    * 
     568    * @see com.modestmaps.Map#EVENT_STOP_ZOOMING 
    475569    */ 
    476570    public function onStopZoom():Void 
    …… 
    483577    * Dispatches EVENT_ZOOMED_BY when the map is zooomed. 
    484578    * Callback arguments includes delta:Number, difference in levels from zoom start. 
     579    * 
     580    * @param    Change in level since beginning of zoom. 
     581    * 
     582    * @see com.modestmaps.Map#EVENT_ZOOMED_BY 
    485583    */ 
    486584    public function onZoomed(delta:Number):Void 
    …… 
    492590   /** 
    493591    * Dispatches EVENT_START_PANNING when the map starts to be panned. 
     592    * 
     593    * @see com.modestmaps.Map#EVENT_START_PANNING 
    494594    */ 
    495595    public function onStartPan():Void 
    …… 
    501601   /** 
    502602    * Dispatches EVENT_STOP_PANNING when the map stops being panned. 
     603    * 
     604    * @see com.modestmaps.Map#EVENT_STOP_PANNING 
    503605    */ 
    504606    public function onStopPan():Void 
    …… 
    511613    * Dispatches EVENT_PANNED_BY when the map is panned. 
    512614    * Callback arguments includes delta:Point, difference in pixels from pan start. 
     615    * 
     616    * @param    Change in position since beginning of pan. 
     617    * 
     618    * @see com.modestmaps.Map#EVENT_PANNED_BY 
    513619    */ 
    514620    public function onPanned(delta:Point):Void 
    …… 
    521627    * Dispatches EVENT_RESIZED_TO when the map is resized. 
    522628    * Callback arguments include width:Number and height:Number. 
     629    * 
     630    * @see com.modestmaps.Map#EVENT_RESIZED_TO 
    523631    */ 
    524632    public function onResized():Void