OpenLayers OpenLayers

Changeset 3728

Show
Ignore:
Timestamp:
07/13/07 07:14:46 (1 year ago)
Author:
crschmidt
Message:

Documentation improvements provided by Glen Stampoultzis. (Thanks Glen!) Closes
#825, #836.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/openlayers/doc/authors.txt

    r3545 r3728  
    1616Cameron Shorter                                                               
    1717Paul Spencer                                                                  
     18Glen Stampoultzis 
    1819James Stembridge 
    1920Erik Uzureau 

  • trunk/openlayers/lib/OpenLayers/Control.js

    r3672 r3728  
    44 
    55/** 
    6 * Class: OpenLayers.Control 
    7 * Controls affect the display or behavior of the map. They allow everything 
    8 * from panning and zooming to displaying a scale indicator. 
    9 */ 
     6 * Class: OpenLayers.Control 
     7 * Controls affect the display or behavior of the map. They allow everything 
     8 * from panning and zooming to displaying a scale indicator. Controls by  
     9 * default are added to the map they are contained within however it is 
     10 * possible to add a control to an external div by passing the div in the 
     11 * options parameter. 
     12 *  
     13 * Example: 
     14 * The following example shows how to add many of the common controls 
     15 * to a map. 
     16 *  
     17 * > var map = new OpenLayers.Map('map', { controls: [] }); 
     18 * > 
     19 * > map.addControl(new OpenLayers.Control.PanZoomBar()); 
     20 * > map.addControl(new OpenLayers.Control.MouseToolbar()); 
     21 * > map.addControl(new OpenLayers.Control.LayerSwitcher({'ascending':false})); 
     22 * > map.addControl(new OpenLayers.Control.Permalink()); 
     23 * > map.addControl(new OpenLayers.Control.Permalink('permalink')); 
     24 * > map.addControl(new OpenLayers.Control.MousePosition()); 
     25 * > map.addControl(new OpenLayers.Control.OverviewMap()); 
     26 * > map.addControl(new OpenLayers.Control.KeyboardDefaults()); 
     27 * 
     28 * The next code fragment is a quick example of how to intercept  
     29 * shift-mouse click to display the extent of the bounding box 
     30 * dragged out by the user.  Usually controls are not created 
     31 * in exactly this manner.  See the source for a more complete  
     32 * example: 
     33 * 
     34 * > var control = new OpenLayers.Control(); 
     35 * > OpenLayers.Util.extend(control, { 
     36 * >     draw: function () { 
     37 * >         // this Handler.Box will intercept the shift-mousedown 
     38 * >         // before Control.MouseDefault gets to see it 
     39 * >         this.box = new OpenLayers.Handler.Box( control,  
     40 * >             {"done": this.notice}, 
     41 * >             {keyMask: OpenLayers.Handler.MOD_SHIFT}); 
     42 * >         this.box.activate(); 
     43 * >     }, 
     44 * > 
     45 * >     notice: function (bounds) { 
     46 * >         alert(bounds); 
     47 * >     } 
     48 * > });  
     49 * > map.addControl(control); 
     50 *  
     51 */ 
    1052OpenLayers.Control = OpenLayers.Class.create(); 
    1153 
    …… 
    64106    /** 
    65107     * Constructor: OpenLayers.Control 
    66      * Create an OpenLayers Control. 
     108     * Create an OpenLayers Control.  The options passed as a parameter 
     109     * directly extend the control.  For example passing the following: 
     110     *  
     111     * > var control = new OpenLayers.Control({div: myDiv}); 
     112     * 
     113     * Overrides the default div attribute value of null. 
    67114     *  
    68115     * Parameters: 
    …… 
    82129    /** 
    83130     * Method: destroy 
     131     * The destroy method is used to perform any clean up before the control 
     132     * is dereferenced.  Typically this is where event listeners are removed 
     133     * to prevent memory leaks. 
    84134     */ 
    85135    destroy: function () { 
    …… 
    94144     * Method: setMap 
    95145     * Set the map property for the control. This is done through an accessor 
    96      *   so that subclasses can override this and take special action once  
    97      *   they have their map variable set.  
     146     * so that subclasses can override this and take special action once  
     147     * they have their map variable set.  
    98148     * 
    99149     * Parameters: 
    …… 
    108158   
    109159    /** 
    110      * Method: draw  
    111      * 
    112      * Parameters: 
    113      * px - {<OpenLayers.Pixel>}  
     160     * Method: draw 
     161     * The draw method is called when the control is ready to be displayed 
     162     * on the page.  If a div has not been created one is created.  Controls 
     163     * with a visual component will almost always want to override this method  
     164     * to customize the look of control.  
     165     * 
     166     * Parameters: 
     167     * px - {<OpenLayers.Pixel>} The top-left pixel position of the control 
     168     *      or null. 
    114169     * 
    115170     * Return: 
    …… 
    131186    /** 
    132187     * Method: moveTo 
     188     * Sets the left and top style attributes to the passed in pixel  
     189     * coordinates. 
    133190     * 
    134191     * Parameters: 
    …… 
    144201    /** 
    145202     * Method: activate 
     203     * Explicitly activates a control and it's associated 
     204     * handler if one has been set.  Controls can be 
     205     * deactivated by calling the deactivate() method. 
    146206     *  
    147207     * Return: 
    148      * {Boolean} 
     208     * {Boolean}  True if the control was successfully activated or 
     209     *            false if the control was already active. 
    149210     */ 
    150211    activate: function () { 
    …… 
    161222    /** 
    162223     * Method: deactivate 
     224     * Deactivates a control and it's associated handler if any.  The exact 
     225     * effect of this depends on the control itself. 
    163226     *  
    164227     * Return: 
    165      * {Boolean} 
     228     * {Boolean} True if the control was effectively deactivated or false 
     229     *           if the control was already inactive. 
    166230     */ 
    167231    deactivate: function () { 

  • trunk/openlayers/lib/OpenLayers/Icon.js

    r3686 r3728  
    66/** 
    77 * Class: OpenLayers.Icon 
     8 *  
     9 * The icon represents a graphical icon on the screen.  Typically used in 
     10 * conjunction with a <OpenLayers.Marker> to represent markers on a screen. 
     11 * 
     12 * An icon has a url, size and position.  It also contains an offset which  
     13 * allows the center point to be represented correctly.  This can be 
     14 * provided either as a fixed offset or a function provided to calculate 
     15 * the desired offset.  
     16 *  
    817 */ 
    918OpenLayers.Icon = OpenLayers.Class.create(); 
    …… 
    6675    /**  
    6776     * Method: destroy 
    68      * nullify references to prevent circular references and memory leaks 
     77     * Nullify references and remove event listeners to prevent circular  
     78     * references and memory leaks 
    6979     */ 
    7080    destroy: function() { 

  • trunk/openlayers/lib/OpenLayers/Map.js

    r3706 r3728  
    1111 * Instances of OpenLayers.Map are interactive maps embedded in a web page. 
    1212 * Create a new map with the <OpenLayers.Map> constructor. 
     13 *  
     14 * On their own maps do not provide much functionality.  To extend a map 
     15 * it's necessary to add controls (<OpenLayers.Control>) and  
     16 * layers (<OpenLayers.Layer>) to the map.  
    1317 */ 
    1418OpenLayers.Map = OpenLayers.Class.create(); 

  • trunk/openlayers/lib/OpenLayers/Marker.js

    r3686 r3728  
    1010 * Class: OpenLayers.Marker 
    1111 * Instances of OpenLayers.Marker are a combination of a  
    12  * <OpenLayers.LonLat> and an <OpenLayers.Icon>. 
     12 * <OpenLayers.LonLat> and an <OpenLayers.Icon>.   
     13 * 
     14 * Markers are generally added to a special layer called 
     15 * <OpenLayers.Layer.Makers>. 
     16 * 
     17 * Example: 
     18 * (code) 
     19 * var markers = new OpenLayers.Layer.Markers( "Markers" ); 
     20 * map.addLayer(markers); 
     21 * 
     22 * var size = new OpenLayers.Size(10,17); 
     23 * var offset = new OpenLayers.Pixel(-(size.w/2), -size.h); 
     24 * var icon = new OpenLayers.Icon('http://boston.openguides.org/markers/AQUA.png',size,offset); 
     25 * markers.addMarker(new OpenLayers.Marker(new OpenLayers.LonLat(0,0),icon)); 
     26 * 
     27 * (end) 
    1328 */ 
    1429OpenLayers.Marker = OpenLayers.Class.create(); 
    …… 
    1732    /**  
    1833     * Property: icon  
    19      * {<OpenLayers.Icon>}  
     34     * {<OpenLayers.Icon>} The icon used by this marker. 
    2035     */ 
    2136    icon: null, 
    …… 
    2944    /**  
    3045     * Property: events  
    31      * {<OpenLayers.Events>} 
     46     * {<OpenLayers.Events>} the event handler. 
    3247     */ 
    3348    events: null, 
    …… 
    3550    /**  
    3651     * Property: map  
    37      * {<OpenLayers.Map>} 
     52     * {<OpenLayers.Map>} the map this marker is attached to 
    3853     */ 
    3954    map: null, 
    …… 
    4257     * Constructor: OpenLayers.Marker 
    4358     * Paraemeters: 
    44      * icon - {<OpenLayers.Icon>} 
    45      * lonlat - {<OpenLayers.LonLat>} 
     59     * icon - {<OpenLayers.Icon>}  the icon for this marker 
     60     * lonlat - {<OpenLayers.LonLat>} the position of this marker 
    4661     */ 
    4762    initialize: function(lonlat, icon) { 
    …… 
    92107    * 
    93108    * Parameters: 
    94     * px - {<OpenLayers.Pixel>} 
     109    * px - {<OpenLayers.Pixel>} the pixel position to move to 
    95110    */ 
    96111    moveTo: function (px) { 
    …… 
    119134    /** 
    120135     * Method: inflate 
     136     * Englarges the markers icon by the specified ratio. 
    121137     * 
    122138     * Parameters: 
    123      * inflate - {float} 
     139     * inflate - {float} the ratio to enlarge the marker by (passing 2 
     140     *                   will double the size). 
    124141     */ 
    125142    inflate: function(inflate) { 

  • trunk/openlayers/lib/OpenLayers/Popup.js

    r3686 r3728  
    66/** 
    77 * Class: OpenLayers.Popup 
     8 * 
     9 * A popup is a small div that can opened and closed on the map. 
     10 * Typically opened in response to clicking on a marker.   
     11 * See <OpenLayers.Marker>.  Popup's don't require their own 
     12 * layer and are added the the map using the <OpenLayers.Map.addPopup> 
     13 * method. 
     14 * 
     15 * Example: 
     16 * (code) 
     17 * popup = new OpenLayers.Popup("chicken",  
     18 *                    new OpenLayers.LonLat(5,40), 
     19 *                    new OpenLayers.Size(200,200), 
     20 *                    "example popup", 
     21 *                    true); 
     22 *        
     23 * map.addPopup(popup); 
     24 * (end) 
    825 */ 
    926OpenLayers.Popup = OpenLayers.Class.create(); 
    …… 
    1835 
    1936    /**  
    20      * Property: events  
    21      * {<OpenLayers.Events>}  
     37     * Property: events  
     38     * {<OpenLayers.Events>} custom event manager  
    2239     */ 
    2340    events: null, 
    2441     
    2542    /** Property: id 
    26      * {String} 
     43     * {String} the unique identifier assigned to this popup. 
    2744     */ 
    2845    id: "", 
    …… 
    3047    /**  
    3148     * Property: lonlat  
    32      * {<OpenLayers.LonLat>}  
     49     * {<OpenLayers.LonLat>} the position of this popup on the map 
    3350     */ 
    3451    lonlat: null, 
    …… 
    3653    /**  
    3754     * Property: div  
    38      * {DOMElement}  
     55     * {DOMElement} the div that contains this popup. 
    3956     */ 
    4057    div: null, 
    …… 
    4259    /**  
    4360     * Property: size  
    44      * {<OpenLayers.Size>}  
     61     * {<OpenLayers.Size>} the width and height of the popup. 
    4562     */ 
    4663    size: null,     
    …… 
    4865    /**  
    4966     * Property: contentHTML  
    50      * {String}  
     67     * {String} The HTML that this popup displays. 
    5168     */ 
    5269    contentHTML: "", 
    …… 
    5471    /**  
    5572     * Property: backgroundColor  
    56      * {String}  
     73     * {String} the background color used by the popup. 
    5774     */ 
    5875    backgroundColor: "", 
    …… 
    6077    /**  
    6178     * Property: opacity  
    62      * {float}  
     79     * {float} the opacity of this popup (between 0.0 and 1.0) 
    6380     */ 
    6481    opacity: "", 
    …… 
    6683    /**  
    6784     * Property: border  
    68      * {String}  
     85     * {String} the border size of the popup.  (eg 2px) 
    6986     */ 
    7087    border: "", 
    …… 
    7289    /**  
    7390     * Property: contentDiv  
    74      * {DOMElement}  
     91     * {DOMElement} a reference to the element that holds the content of 
     92     *              the div. 
    7593     */ 
    7694    contentDiv: null, 
    …… 
    7896    /**  
    7997     * Property: groupDiv  
    80      * {DOMElement}  
     98     * {DOMElement} the parent of <OpenLayers.Popup.contentDiv>  
    8199     */ 
    82100    groupDiv: null, 
    …… 
    84102    /**  
    85103     * Property: padding  
    86      * {int}  
     104     * {int} the internal padding of the content div. 
    87105     */ 
    88106    padding: 5, 
    …… 
    100118    *  
    101119    * Parameters:  
    102     * id - {String}  
    103     * lonlat - {<OpenLayers.LonLat>}  
    104     * size - {<OpenLayers.Size>}  
    105     * contentHTML - {String}  
    106     * closeBox - {Boolean}  
     120    * id - {String} a unqiue identifier for this popup.  If null is passed 
     121    *               an identifier will be automatically generated.  
     122    * lonlat - {<OpenLayers.LonLat>}  The position on the map the popup will 
     123    *                                 be shown. 
     124    * size - {<OpenLayers.Size>}      The size of the popup. 
     125    * contentHTML - {String}          The HTML content to display inside the  
     126    *                                 popup. 
     127    * closeBox - {Boolean}            Whether to display a close box inside 
     128    *                                 the popup.  
    107129    */ 
    108130    initialize:function(id, lonlat, size, contentHTML, closeBox) { 
    …… 
    179201 
    180202    /**  
    181     * method: draw 
    182     *  
     203    * Method: draw 
     204    * Constructs the elements that make up the popup. 
     205    * 
    183206    * Parameters: 
    184     * px - {<OpenLayers.Pixel>}  
     207    * px - {<OpenLayers.Pixel>} the position the popup in pixels. 
    185208    *  
    186209    * Return: 
    …… 
    217240 
    218241    /** 
    219     * Method: moveTo 
    220     *  
    221     * Parameters: 
    222     * px - {<OpenLayers.Pixel>}  
    223     */ 
     242    * Method: moveTo 
     243    *  
     244    * Parameters: 
     245    * px - {<OpenLayers.Pixel>} the top and left position of the popup div.  
     246    */ 
    224247    moveTo: function(px) { 
    225248        if ((px != null) && (this.div != null)) { 
    …… 
    230253 
    231254    /** 
    232      * method: visible 
     255     * Method: visible 
    233256     * 
    234257     * Returns:       
    …… 
    241264    /** 
    242265     * Method: toggle 
     266     * Toggles visibility of the popup. 
    243267     */ 
    244268    toggle: function() { 
    …… 
    248272    /** 
    249273     * Method: show 
     274     * Makes the popup visible. 
    250275     */ 
    251276    show: function() { 
    …… 
    255280    /** 
    256281     * Method: hide 
     282     * Makes the popup invisible. 
    257283     */ 
    258284    hide: function() { 
    …… 
    261287 
    262288    /** 
    263     * Method: setSize 
    264     *  
    265     * Parameters: 
    266     * size - {<OpenLayers.Size>}  
    267     */ 
     289     * Method: setSize 
     290     * Used to adjust the size of the popup.  
     291     * 
     292     * Parameters: 
     293     * size - {<OpenLayers.Size>} the new size of the popup in pixels. 
     294     */ 
    268295    setSize:function(size) {  
    269296        if (size != undefined) { 
    …… 
    283310    /** 
    284311    * Method: setBackgroundColor 
    285     * 
     312    * Sets the background color of the popup. 
    286313    * Parameters: 
    287     * color - {String}  
     314    * color - {String} the background color.  eg "#FFBBBB" 
    288315    */ 
    289316    setBackgroundColor:function(color) {  
    …… 
    298325     
    299326    /** 
    300     * Method: setOpacity 
    301     *  
    302     * Parameters: 
    303     * opacity - {float}  
    304     */ 
     327     * Method: setOpacity 
     328     * Sets the opacity of the popup. 
     329     *  
     330     * Parameters: 
     331     * opacity - {float} A value between 0.0 (transparent) and 1.0 (solid).    
     332     */ 
    305333    setOpacity:function(opacity) {  
    306334        if (opacity != undefined) { 
    …… 
    318346     
    319347    /** 
    320     * Method: setBorder 
    321     * 
    322     * Parameters: 
    323     * border - {int}  
    324     */ 
     348     * Method: setBorder 
     349     * Sets the border style of the popup. 
     350     * 
     351     * Parameters: 
     352     * border - {String} The border style value. eg 2px  
     353     */ 
    325354    setBorder:function(border) {  
    326355        if (border != undefined) { 
    …… 
    335364    /** 
    336365     * Method: setContentHTML 
     366     * Allows the user to set the HTML content of the popup. 
    337367     * 
    338368     * Parameters: 
    339      * contentHTML - {String}  
     369     * contentHTML - {String} HTML for the div. 
    340370     */ 
    341371    setContentHTML:function(contentHTML) {