Difference between revisions of "Linden Lab Official:Map API Reference"

From Second Life Wiki
Jump to navigation Jump to search
(Updated for version 2 of API)
 
(71 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Bounds ==
{{Supported API}}
Represents the bounds for a 2D coordinate space. See the [http://secondlife.com/developers/mapapi/index.html#adv_bounds guide] for more.
{{:API Portal/navigation|map}}
'''NOTE:''' See the [[Linden Lab Official:Map API Introduction#Release notes|Release Notes]] for information on new features and known issues.
{{API Constructor|  
__TOC__
Bounds (
<br clear="all"/>
xMin,
== Global functions ==
xMax,
yMin,
yMax)
}}
 
'''Properties'''


{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
{| border="1" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Function
!valign="top"| Default
!valign="top"| Return Value
!valign="top"| Description
!valign="top"| Description


|-
|-
|xMin
|valign="top" class="signature"|
|Zero
SLMap(
|Minimum x coordinate of the bounding window.
[https://developer.mozilla.org/en/DOM/element HTMLElement] element)
 
|[[#Map|Map]]
|Creates a new map inside the specified DOM element.
|-
|-
|xMax
|valign="top" class="signature"|
|Zero
gotoSLURL(
|Maximum x coordinate of the bounding window.
x Number,
 
y Number,
|-
[[#Map|Map]] lmap)
|yMin
|None
|Zero
|Pans the map to display the specified inworld location.
|Minimum y coordinate of the bounding window.
 
|-
|yMax
|Zero
|Maximum y coordinate of the bounding window.
|}
|}


NOTE: The default values are applied if any of the properties is not specified in the constructor call.
== Objects ==


== Icon ==
=== Map ===
Represents an icon to used as a marker.  
This class is the Leaflet class that represents the map. For more information, see [http://leafletjs.com/reference-1.0.2.html#map the Leaflet Map reference].


{{API Constructor|  
{{API Constructor|  
Icon (
[http://leafletjs.com/reference-1.0.2.html#map Map] SLMap([https://developer.mozilla.org/en/DOM/element HTMLElement] container)
[[#Img|Img]] mainImage,
[[#Img|Img]] shadowImage )
}}
}}


Creates a new icon to be used on the map. The optional second parameter specifies a shadow image. See the [http://secondlife.com/developers/mapapi/index.html#adv_png guide] for more.
Creates a Leaflet map configured to display a map of Second Life.
shadowImage defaults to null.


== Img ==
The map is generated with a click event handler that calls '''gotoSLURL()''' to display a popup with a “Visit this location” link.
Represents an image to be used as an icon.  


{{API Constructor|
==== Useful Methods ====
Img (
String imageSource,
Number width,
Number height,
Boolean hasAlphaChannel )
}}
Creates a new image to be used on the map.
 
The width and height parameters must be integer values.
 
The optional hasAlphaChannel parameter specifies whether the image is a 24-bit PNG image with alpha channel transparency. Its default avlue is  false. See the [http://secondlife.com/developers/mapapi/index.html#adv_png guide] for more.


== MapWindow ==
For other methods, see [http://leafletjs.com/reference-1.0.2.html#map-method the Leaflet Map methods reference].
This class represents a window placed over the map.


{{API Constructor|
{| border="1" cellspacing="0" cellpadding="3" rules="all" class="apitable"
MapWindow (
String windowText,
options )
}}
 
Creates a new map window. The given text will be what is contained in the window. Note, HTML can be used but quotes must be escaped correctly otherwise javascript errors will occur.
 
The options argument is an object literal that specifies the window options, as described in the following table.
 
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
 
|-
|alwaysOnTop
|false
|Whether window is always displayed on top of other windows.
 
|-
|noEffect
|false
|Whether window appears with fade-in and fade-out effect.
 
|-
|closeOnMove
|false
|Whether window is closed when user drags the map.
 
|-
|bringToTop
|false
|Whether window is brought to the top when user clicks other windows.
 
|-
|width
|252
|Width of the window in pixels.
 
|-
|height
|236
|Height of the window in pixels.
 
|-
|padding
|10
|Padding of the window in pixels.
|}
 
== Marker ==
Represents a marker to be added on the map.
 
{{API Constructor|
Marker (
Array icons,
[[#XYPoint|XYPoint]] coordinate,
[[#MarkerOptions|MarkerOptions]] markerOptions )
}}
 
Creates a new marker to be placed on the map at given coordinate. The first parameter is an array of icons of length 6. Each icon in the array corresponds to a zoom level, icons[0] being the icon used at the close zoom (level 0).
 
The optional markerOptions argument is a [[#MarkerOptions|MarkerOptions]] object that defaults to null.
 
== MarkerOptions ==
 
'''Properties'''
 
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
 
|-
|centerOnClick
|false
|centers the map on the marker when clicked.
 
|-
|clickHandler
|null
|sets a click handler.
 
|-
|onMouseOverHandler
|null
|sets a handler that gets executed during an onmouseover event.
 
|-
|onMouseOutHandler
|null
|sets a handler that gets executed during an onmouseout event.
 
|-
|autopanOnClick
|true
|the map will automatically pan the map if part of the associated MapWindow would have been clipped by an edge of the map when it was opened.
 
|-
|autopanPadding
|45
|this number represents how close the window needs to be to an edge of the map for autopan to trigger.
 
|-
|verticalAlign
|"middle"
|also can be set to "top" and "bottom". This specifies how the marker is vertically aligned.
 
|-
|horizontalAlign
|"center"
|also can be set as "left" or "right". This specifies how the marker is horizontally aligned.
 
|-
|zLayer
|0
|Specifies the layer the marker will render on. For example, if a marker having zLayer = 1 and another marker having zLayer = 0 overlap, the marker with zLayer = 1 will be on top.
|}
 
The clickHandler, onMouseOverHandler, and onMouseOutHandler options specify an optional functions that get called when their respective events occur. See the [http://secondlife.com/developers/mapapi/index.html#adv_marker_bind guide] for more.
 
== SLMap ==
This class represents the map.
 
{{API Constructor|
SLMap (
HTMLElement container,
[[#SLMapOptions|SLMapOptions]] options )
}}
 
Creates the map. The options argument defaults to null.
 
=== Methods ===
 
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
|- bgcolor="#A7C1F2"
!valign="top"| Method
!valign="top"| Method
Line 217: Line 53:
|-
|-
|valign="top" class="signature"|
|valign="top" class="signature"|
addMapWindow(
[http://leafletjs.com/reference-1.0.2.html#map-setview setView](  
MapWindow mapWindow,
[http://leafletjs.com/reference-1.0.2.html#latlng LatLng] center,
XYPoint coord )
Number zoom)
|valign="top"| None
|valign="top"| [http://leafletjs.com/reference-1.0.2.html#map Map]
|valign="top"| Adds a MapWindow to the map at specified coordinate.
|valign="top"| Centers and zooms the map to the specified location.  Argument zoom must be an integer value. Note that [http://leafletjs.com/examples/crs-simple/crs-simple.html#this-is-not-the-latlng-youre-looking-for a LatLng is a (Y, X) coordinate], so coordinates passed as ''center'' should be in (Y, X) order.
 
|-
|valign="top" class="signature"|
addMarker(
Marker marker,
MapWindow mapWindow )
|valign="top"| None
|valign="top"| Adds a marker. If the optional mapWindow argument is null, then clicking on the marker will not open a window.
 
|-
|valign="top" class="signature"|
clickMarker(
Marker marker)
|valign="top"| None
|valign="top"| Simulates a clicking a marker. Will recenter the pan if its not currently in the viewport of the map.
 
|-
|valign="top" class="signature"|
disableDragging()
|valign="top"| None
|valign="top"| Disables all dragging on the map. Note: panning controls will still work.
 
|-
|valign="top" class="signature"|
enableDragging()
|valign="top"| None
|valign="top"| Re-enables dragging on the map if it was disabled.
 
|-
|valign="top" class="signature"|
enterAndZoomAtSLCoord(
XYPoint coordinate,
int zoom)
|valign="top"| None
|valign="top"| Centers and zooms the map to the specified location.
 
|-
|valign="top" class="signature"|
getCurrentZoomLevel()
|valign="top"| None
|valign="top"| Gets the current zoom level (1-6). See [http://secondlife.com/developers/mapapi/index.html#about_zoom about zoom levels].
 
|-
|valign="top" class="signature"|
getMapCenter()
|valign="top"|XYPoint
|valign="top"| Returns the current map center. See [http://secondlife.com/developers/mapapi/index.html#about_coords about coordinates].
 
|-
|valign="top" class="signature"|
getViewportBounds()  
|valign="top"|Bounds
|valign="top"| Gets the viewport bounds. See [http://secondlife.com/developers/mapapi/index.html#about_coords about coordinates].
 
|-
|valign="top" class="signature"|
panDown()
|valign="top"| None
|valign="top"| Pans the map to the down by half its width.
 
|-
|valign="top" class="signature"|
panLeft()
|valign="top"| None
|valign="top"| Pans the map to the left by 1/2 its width.
 
|-
|valign="top" class="signature"|
panOrRecenterToSLCoord(
XYPoint coord,
Boolean recenter )
|valign="top"| None
|valign="top"| Pans the map to the given coordinate if it is currently in the viewport (in the user's view). Otherwise, recenters the map to the given coordinate.  The optional recenter argument  specifies whether to center the given coordinate even it if is currently in the viewport. Its default value is false.  
 
|-
|valign="top" class="signature"|
panRight()
|valign="top"| None
|valign="top"| Pans the map to the right by 1/2 its width.  
 
|-
|valign="top" class="signature"|
panUp()
|valign="top"| None
|valign="top"| Pans the map to the up by 1/2 its width.
 
|-
|valign="top" class="signature"|
removeAllMarkers() 
|valign="top"| None
|valign="top"| Removes all markers.
 
|-
|valign="top" class="signature"|
removeMarker(
Marker marker) 
|valign="top"| None
|valign="top"| Removes a marker.
 
|-
|valign="top" class="signature"|
setCurrentZoomLevel(
int zoom)
|valign="top"| None
|valign="top"| Sets the zoom level to specified zoom.
 
|-
|valign="top" class="signature"|
zoomIn()
|valign="top"| None
|valign="top"| Zooms in on the map if the map is not already all the way zoomed in.
 
|-
|valign="top" class="signature"|
zoomOut()
|valign="top"| None
|valign="top"| Zooms out on the map if the map is not already all the way zoomed out.
|}
 
== SLMapOptions ==
This class represents optional arguments to the SLMap constructor. It has no constructor, but is instantiated as an object literal.
 
'''Properties'''
 
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
 
|-
|hasZoomControls
|true
|Whether the map has zoom controls.
 
|-
|hasPanningControls
|true
|Whether the map has pan controls.
|-
|doubleClickHandler
|null
| Specifies a double click function.
 
|-
|singleClickHandler
|null
|Specifies a single click function
|-
|onStateChangedHandler
|null
|Specifies an onstatechanged handler function
 
|-
|zoomMin
|6
|Specifies an minimum level a map can be zoomed to. Currently the maximum for this value is 7.
 
|-
|zoomMax
|1
|Specifies an maximum level a map can be zoomed to. Currently the minimum for this value is 1.
|}
 
The '''doubleClickHandler''' and '''singleClickHandler''' option can be assigned to call a function whenever a place on the map is double-clicked or single-clicked respectively. See the [http://secondlife.com/developers/mapapi/index.html#adv_double_click guide] for more.
 
The '''onStateChangedHandler''' option can be assigned to call a function whenever the "state" of the map changes (i.e. whenever the map bounds change). Likewise, see the [http://secondlife.com/developers/mapapi/index.html#adv_onstatechanged guide] for more.
 
== SLPoint ==
 
Not currently implemented.
 
<!--
Represents a point in Second Life.
 
 
{{API Constructor|
SLPoint (String Region_name,  
Int local_x,
Int local_y )  
 
Creates an SLPoint object.
 
'''Properties'''
 
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
|-
|x
|X coordinate
 
|-
|y
|Y coordinate
|}
|}


Note - The region name is case insensitive; for example, so to specificy "Da Boom" region, use either:
== Utility URLs ==
 
These map helper functions are available from the caps server. The JSON-like results return text that Javascript could eval(), but scripts coming from outside should parse them the "hard" way for safety.
* SLPoint("da boom")
* SLPoint("dA bOOm")
-->
== XYPoint ==
Represents a point in 2D coordinate space.  
 
{{API Constructor|
XYPoint (
Float x,  
Float y )
}}


Creates an XYPoint object.
=== Region name from global coordinates ===
https<nowiki></nowiki>://cap.secondlife.com/cap/0/'''b713fe80-283b-4585-af4d-a3b7d9a32492'''?'''var'''=''varName''&'''grid_x'''=''xcoord''&'''grid_y'''=''ycoord''
* '''var''' is arbitrary, for output formatting.
* '''grid_x''' is the region's global x coordinate as an integer.
* '''grid_y''' is the region's global y coordinate as an integer.


'''Properties'''
'''Example'''
https://cap.secondlife.com/cap/0/b713fe80-283b-4585-af4d-a3b7d9a32492?var=region&grid_x=1000&grid_y=1000
:Returns: <pre>var region='Da Boom';</pre>


{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
=== Global coordinates from region name ===
|- bgcolor="#A7C1F2"
https<nowiki></nowiki>://cap.secondlife.com/cap/0/'''d661249b-2b5a-4436-966a-3d3b8d7a574f'''?'''var'''=''varName''&'''sim_name'''=''RegionName''
!valign="top"| Property
* '''var''' is arbitrary, for output formatting.
!valign="top"| Default
* '''sim_name''' is a region on the Second Life map.
!valign="top"| Description


|-
'''Example'''
|x
https://cap.secondlife.com/cap/0/d661249b-2b5a-4436-966a-3d3b8d7a574f?var=coords&sim_name=Da%20Boom
|None
:Returns: <pre>var coords = {'x' : 1000, 'y' : 1000 };</pre>
|X coordinate
 
|-
|y
|None
|Y coordinate
|}

Latest revision as of 18:23, 13 December 2016

NOTE: This is an official Second Life API provided and documented by Linden Lab. Its use is subject to the API Terms of Use.

NOTE: See the Release Notes for information on new features and known issues.


Global functions

Function Return Value Description

SLMap( HTMLElement element)

Map Creates a new map inside the specified DOM element.

gotoSLURL( x Number, y Number, Map lmap)

None Pans the map to display the specified inworld location.

Objects

Map

This class is the Leaflet class that represents the map. For more information, see the Leaflet Map reference.

Constructor

Map SLMap(HTMLElement container)

Creates a Leaflet map configured to display a map of Second Life.

The map is generated with a click event handler that calls gotoSLURL() to display a popup with a “Visit this location” link.

Useful Methods

For other methods, see the Leaflet Map methods reference.

Method Return Value Description

setView( LatLng center, Number zoom)

Map Centers and zooms the map to the specified location. Argument zoom must be an integer value. Note that a LatLng is a (Y, X) coordinate, so coordinates passed as center should be in (Y, X) order.

Utility URLs

These map helper functions are available from the caps server. The JSON-like results return text that Javascript could eval(), but scripts coming from outside should parse them the "hard" way for safety.

Region name from global coordinates

https://cap.secondlife.com/cap/0/b713fe80-283b-4585-af4d-a3b7d9a32492?var=varName&grid_x=xcoord&grid_y=ycoord

  • var is arbitrary, for output formatting.
  • grid_x is the region's global x coordinate as an integer.
  • grid_y is the region's global y coordinate as an integer.

Example 

https://cap.secondlife.com/cap/0/b713fe80-283b-4585-af4d-a3b7d9a32492?var=region&grid_x=1000&grid_y=1000
Returns: 
var region='Da Boom';

Global coordinates from region name

https://cap.secondlife.com/cap/0/d661249b-2b5a-4436-966a-3d3b8d7a574f?var=varName&sim_name=RegionName

  • var is arbitrary, for output formatting.
  • sim_name is a region on the Second Life map.

Example 

https://cap.secondlife.com/cap/0/d661249b-2b5a-4436-966a-3d3b8d7a574f?var=coords&sim_name=Da%20Boom
Returns: 
var coords = {'x' : 1000, 'y' : 1000 };
Retrieved from "https://wiki.secondlife.com/w/index.php?title=Linden_Lab_Official:Map_API_Reference&oldid=1205051"