Linden Lab Official:Map API Reference

From Second Life Wiki
Revision as of 15:46, 22 January 2014 by Maestro Linden (talk | contribs) (Added a warning about missing capability id for BUG-4116)
Jump to navigation Jump to search
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

gotoSLURL( x Number, y Number, SLMap slMap)

None Launches the Second Life Viewer, setting the avatar's location to the specified inworld location.

Objects

Bounds

Represents the bounds for a 2D coordinate space. Typically, you don't construct one explicitly, but rather call the getViewportBounds() method on a SLMap instance.


Constructor

Bounds ( xMin Number, xMax Number, yMin Number, yMax Number)

Properties

Property Default Description
xMin Zero Minimum x coordinate of the bounding window. Must be a postive integer.
xMax Zero Maximum x coordinate of the bounding window. Must be a postive integer.
yMin Zero Minimum y coordinate of the bounding window. Must be a postive integer.
yMax Zero Maximum y coordinate of the bounding window. Must be a postive integer.

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

Example

...
var mapInstance = new SLMap(document.getElementById('map-container'));
var bounds = mapInstance.getViewportBounds();  // This is a Bounds object
...

Icon

Represents an icon to used as a marker.

Constructor

Icon ( Img mainImage, Img shadowImage )

Creates a new icon to be used on the map. The optional second parameter specifies a shadow image. The shadowImage argument is optional and defaults to null.

Example

// create the icons
var forsale_sign = new Img("Forsale.png",80,83, true); // note fourth parameter is true!
var forsale_shadow = new Img("Forsale-shadow.png",98,83, true);
var forsale_icon = new Icon(forsale_sign, forsale_shadow);
var all_images = [forsale_icon, 
                  forsale_icon, 
                  forsale_icon, 
                  forsale_icon, 
                  forsale_icon, 
                  forsale_icon];

// create the marker
var marker = new Marker(all_images, new XYPoint(995,1004));
mapInstance.addMarker(marker);

Img

Represents an image to be used as an icon.

Constructor

Img ( String imageSource, Number width, Number height, Boolean hasAlphaChannel )

The followint table describes the Img object's properites:

Property Default Description
imageSource None URL of image file. Can be a relative or absolute URL.
width None Width of image in pixels (a positive integer).
height None Height of image in pixels (a positive integer).
hasAlphaChannel false Boolean that indicates whether the image is a 24-bit PNG image with alpha channel transparency. Optional parameter.

Example

// create the icons
var forsale_sign = new Img("Forsale.png", 80, 83, true); // Note fourth parameter is true!
var forsale_shadow = new Img("Forsale-shadow.png",98,83, true);
var forsale_icon = new Icon(forsale_sign, forsale_shadow);
var all_images = [forsale_icon, 
                  forsale_icon, 
                  forsale_icon, 
                  forsale_icon, 
                  forsale_icon, 
                  forsale_icon];

// create the marker
var marker = new Marker(all_images, new XYPoint(995,1004));
mapInstance.addMarker(marker);

Methods

Method Return Value Description

isAlpha()

Boolean Returns true if the image has an alpha channel, false otherwise.

MapWindow

This class represents a window placed over the map.

Constructor

MapWindow ( String windowText)

Creates a new map window. The window will display the text specified by the windowText parameter. You can include HTML tags in the windowText, but you must escape quotes, otherwise, you'll get Javascript errors.

Example

var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");
mapInstance.addMapWindow(mapWindow, new XYPoint(997, 1002));

Marker

Represents a marker to be added on the map.

Constructor

Marker ( Array icons, XYPoint coordinate, MarkerOptions markerOptions )

Creates a new marker to be placed on the map at given coordinate. The first parameter is an array of six icon objects. Each icon in the array corresponds to a zoom level, icons[0] being the icon used at the close zoom (level 0).

The MarkerOptions argument is optional.

Properties

Property Default Description
slCoord.x None Second Life x coordinate of the marker
slCoord.y None Second Life y coordinate of the marker

MarkerOptions

Object used to specify optional properties when creating a Marker object.

Properties

Property Default Description
autopanOnClick true If 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 How close the window needs to be (in pixels) to an edge of the map to trigger autopanning.
centerOnClick false If true, centers the map on the marker when user clicks on it.
clickHandler null Event handler function called when user clicks on marker, that is, when onClick event. Optional. The marker is automatically passed as the argument to the function.
horizontalAlign "center" Specifies how the marker is horizontally aligned. Valid values are:
  • "left"
  • "right"
  • "center"
onMouseOutHandler null Event handler function called when mouse pointer leaves marker, that is, when onmouseout event occurs. Optional.


onMouseOverHandler null Event handler function called when mouse pointer moves over marker, that is, when onmouseover event occurs. Optional.
verticalAlign "middle" Specifies how the marker is vertically aligned. Valid values are:
  • "top"
  • "bottom"
  • "middle"
zLayer 0 Specifies the CSS z-index of the marker. A marker with a greater z-index will display over one with a lower z-index. For example, if a marker having zLayer of one (1) and another marker having zLayer of zero (0) overlap, the first one will be on top. For more information on z-index, see Understanding CSS z-index.

The optional clickHandler, onMouseOverHandler, and onMouseOutHandler properties specify event handler functions called when the respective events occur.

Example

The following code sets the clickHandler, onMouseOverHandler, and onMouseOutHandler properties to assign an event handler function called when theuser clicks on the marker, moves the mouse pointer over the marker, and moves the mouse pointer off the marker, respectively:

var doMarkerAction = function(marker) {alert("an event occured at (" + marker.slCoord.x + "," + marker.slCoord.y + ")"); };

var marker = new Marker(all_images, 
                        new XYPoint(997,1002), 
                        {clickHandler: doMarkerAction, 
                         onMouseOutHandler:  doMarkerAction, 
                         onMouseOverHandler: doMarkerAction});

SLMap

This class represents the map.

Constructor

SLMap ( HTMLElement container, SLMapOptions options )

Creates the map. The options argument defaults to null.

By default the map has a clickhandler function that calls gotoSLURL(), passing the location of the click. By default, the map has a doubleclickhandler function that calls centerAndZoomAtSLCoord(), passing the location of the double click.

Methods

Method Return Value Description

addMapWindow( MapWindow mapWindow, XYPoint coord )

None Add a MapWindow to the map at specified coordinate.

addMarker( Marker marker, MapWindow mapWindow )

None Add a marker. If the optional mapWindow argument is null, then clicking on the marker will not open a window.

centerAndZoomAtSLCoord( XYPoint coordinate, Number zoom)

None Centers and zooms the map to the specified location. Argument zoom must be an integer value.

clickMarker( Marker marker)

None Simulates clicking a marker. Recenters the pan if its not currently in the viewport of the map.

disableDragging()

None Disables all dragging on the map. Note: panning controls will still work.

enableDragging()

None Re-enables dragging on the map if it was disabled.

getCurrentZoomLevel()

None Gets the current zoom level (1-6). For more information, see Zoom levels.

getMapCenter()

XYPoint Returns the current map center. For more information, see About coordinates.

getViewportBounds()

Bounds Gets the viewport bounds. For more information, see About coordinates.

panDown()

None Pan the map down by half its width.

panLeft()

None Pan the map left by half its width.

panOrRecenterToSLCoord( XYPoint coord, Boolean recenter )

None Pan 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.

panRight()

None Pan the map right by half its width.

panUp()

None Pan the map up by half its width.

removeAllMarkers()

None Remove all markers.

removeMarker( Marker marker)

None Remove a marker.

setCurrentZoomLevel( Number zoom)

None Set the zoom level to specified value. Argument zoom must be an integer.

zoomIn()

None Zoom in on the map if the map is not already all the way zoomed in.

zoomOut()

None Zoom 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, so you must instantiate it as an object literal.

Properties

Property Default Description
hasZoomControls true Whether the map has zoom controls.
hasPanningControls true Whether the map has pan controls.
hasOverviewMapControl true Specifies whether to display overview control in lower right of map.
doubleClickHandler null Specifies event handler function called when user double-clicks on the map.
clickHandler null Specifies event handler function called when user clicks once on the map.
onStateChangedHandler null Specifies an event handler function to call when map state changes, that is:
  • Map pans
  • Zoom level changes
zoomMin 6 Specifies an minimum level a map can be zoomed to. Maximum is seven (7).
zoomMax 1 Specifies an maximum level a map can be zoomed to. Minimum is one (1).

Example

Set the onStateChangedHandler property to define an event handler called whenever the "state" of the map changes (for example, when the map bounds change).

var doSomething = function(x,y) {
                                   alert("The map state changed.");
                                 };
mapInstance = new SLMap(document.getElementById('map-container'), 
                        {onStateChangedHandler: doSomething});

SLPoint

Not currently implemented.

XYPoint

Represents a point in 2D coordinate space.

Constructor

XYPoint ( Number x, Number y )

Creates an XYPoint object.

Properties

Property Default Description
x None X coordinate
y None Y coordinate

Example

 mapInstance1.centerAndZoomAtSLCoord(new XYPoint(997.5, 1001.5), 2);

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

Note: the capability for this service, b713fe80-283b-4585-af4d-a3b7d9a32492, is currently unavailable. Maestro Linden 14:46, 22 January 2014 (PST)

 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 };

Voice support

(This was for support of the former Second Life voice map. It's documented for completeness, but basically all regions have supported voice for a long time.)

https://secondlife.com/app/voicemap/index.php?var=varName&x=xcoord&y=ycoord&blocksize=num
  • var is arbitrary, for output formatting.
  • x is the region's global x coordinate as an integer.
  • y is the region's global y coordinate as an integer.
  • blocksize controls now many regions are reported. blocksize=1 returns a single region's information, blocksize=2 returns information for a 2 x 2 square of regions (4 total), and so on.

Example

https://secondlife.com/app/voicemap/index.php?var=voice&x=1000&y=1000&blocksize=1
Returns:
var voice = [{x: 1000, y: 1000, voiceEnabled: new Date(f), name: 'a'}]