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

From Second Life Wiki
Jump to navigation Jump to search
Line 1: Line 1:
== Bounds ==
Represents the bounds for a 2D coordinate space. See the [http://secondlife.com/developers/mapapi/index.html#adv_bounds guide] for more.
{{API Constructor|
Bounds (
xMin,
xMax,
yMin,
yMax)
}}
'''Properties'''
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
|-
|xMin
|Minimum x coordinate of the bounding window.
|Zero.
|-
|xMax
|Maximum x coordinate of the bounding window.
|Zero
|-
|yMin
|Minimum y coordinate of the bounding window.
|Zero
|-
|yMax
|Maximum y coordinate of the bounding window.
|Zero
|}
NOTE: The default values are applied if any of the properties is not specified in the constructor call.
== Icon ==
Represents an icon to used as a marker.
{{API Constructor|
Icon (Img mainImage,
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.
shadowImage defaults to null.
== Img ==
Represents an image to be used as an icon.
{{API Constructor|
Img (String imageSource,
int width,
int height,
Boolean hasAlphaChannel )
}}
Creates a new image to be used on the map. The optional fourth parameter is for specifying whether you are using a 24-bit PNG image with alpha channel transparency. See the [http://secondlife.com/developers/mapapi/index.html#adv_png guide] for more.
hasAlphaChannel defaults to false.
== MapWindow ==
This class represents a window placed over the map.
{{API Constructor|
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 second optional argument is a hash of window options. They are (defaults are in parenthesis):
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
|-
|alwaysOnTop
|false
|specifies if this window should always be on top of other windows
|-
|noEffect
|false
|specifies if window will appear with fade-in and fade-out effect
|-
|closeOnMove
|false
|specifies if this window will be closed when the map is dragged
|-
|bringToTop
|false
|specifies if this window will be brought to the top if other windows are clicked
|-
|width
|252
|specifies the width of the window in pixels
|-
|height
|236
|specifies the height of the window in pixels
|-
|padding
|10
|specifies the padding of the window in pixels
|}
== Marker ==
Represents a marker to be added on the map.
{{API 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 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).</nowiki>
The optional markerOptions argument is a 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 ==
== SLMap ==
This class represents the map.
This class represents the map.
=== Constructor ===


{{API Constructor|  
{{API Constructor|  
Line 54: Line 238:
|valign="top"| None
|valign="top"| None
|valign="top"| Re-enables dragging on the map if it was disabled.  
|valign="top"| Re-enables dragging on the map if it was disabled.  


|-
|-
Line 150: Line 333:
This class represents optional arguments to the SLMap constructor. It has no constructor, but is instantiated as an object literal.
This class represents optional arguments to the SLMap constructor. It has no constructor, but is instantiated as an object literal.


=== Properties ===
'''Properties'''


{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
Line 196: Line 379:


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.  
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.  
== MapWindow ==
This class represents a window placed over the map.
=== Constructor ===
{{API Constructor|
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 second optional argument is a hash of window options. They are (defaults are in parenthesis):
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
|-
|alwaysOnTop
|false
|specifies if this window should always be on top of other windows
|-
|noEffect
|false
|specifies if window will appear with fade-in and fade-out effect
|-
|closeOnMove
|false
|specifies if this window will be closed when the map is dragged
|-
|bringToTop
|false
|specifies if this window will be brought to the top if other windows are clicked
|-
|width
|252
|specifies the width of the window in pixels
|-
|height
|236
|specifies the height of the window in pixels
|-
|padding
|10
|specifies the padding of the window in pixels
|}
== Img ==
Represents an image to be used as an icon.
=== Constructor ===
{{API Constructor|
Img (String imageSource,
int width,
int height,
Boolean hasAlphaChannel )
}}
Creates a new image to be used on the map. The optional fourth parameter is for specifying whether you are using a 24-bit PNG image with alpha channel transparency. See the [http://secondlife.com/developers/mapapi/index.html#adv_png guide] for more.
hasAlphaChannel defaults to false.
== Icon ==
Represents an icon to used as a marker.
=== Constructor ===
{{API Constructor|
Icon (Img mainImage,
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.
shadowImage defaults to null.
== Marker ==
Represents a marker to be added on the map.
=== Constructor ===
{{API 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 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).</nowiki>
The optional markerOptions argument is a 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.


== SLPoint ==
== SLPoint ==
Line 351: Line 387:
Represents a point in Second Life.  
Represents a point in Second Life.  


=== Constructor ===
 
{{API Constructor|  
{{API Constructor|  
SLPoint (String Region_name,  
SLPoint (String Region_name,  
Line 359: Line 395:
Creates an SLPoint object.
Creates an SLPoint object.


=== Properties ===
'''Properties'''


{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
Line 383: Line 419:
Represents a point in 2D coordinate space.  
Represents a point in 2D coordinate space.  


=== Constructor ===
{{API Constructor|  
{{API Constructor|  
XYPoint (
XYPoint (
Line 392: Line 427:
Creates an XYPoint object.
Creates an XYPoint object.


=== Properties ===
'''Properties'''


{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
Line 410: Line 445:
|Y coordinate  
|Y coordinate  
|}
|}
== Bounds ==
Represents the bounds for a 2D coordinate space. See the [http://secondlife.com/developers/mapapi/index.html#adv_bounds guide] for more.
{{API Constructor|
Bounds (
xMin,
xMax,
yMin,
yMax)
}}
=== Properties ===
{| border="2" cellspacing="0" cellpadding="3" rules="all" class="apitable"
|- bgcolor="#A7C1F2"
!valign="top"| Property
!valign="top"| Default
!valign="top"| Description
|-
|xMin
|Minimum x coordinate of the bounding window.
|Zero.
|-
|xMax
|Maximum x coordinate of the bounding window.
|Zero
|-
|yMin
|Minimum y coordinate of the bounding window.
|Zero
|-
|yMax
|Maximum y coordinate of the bounding window.
|Zero
|}
NOTE: The default values are applied if any of the properties is not specified in the constructor call.

Revision as of 18:09, 22 January 2009

Bounds

Represents the bounds for a 2D coordinate space. See the guide for more.

Constructor

Bounds ( xMin, xMax, yMin, yMax)

Properties

Property Default Description
xMin Minimum x coordinate of the bounding window. Zero.
xMax Maximum x coordinate of the bounding window. Zero
yMin Minimum y coordinate of the bounding window. Zero
yMax Maximum y coordinate of the bounding window. Zero

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

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. See the guide for more. shadowImage defaults to null.

Img

Represents an image to be used as an icon.

Constructor

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

Creates a new image to be used on the map. The optional fourth parameter is for specifying whether you are using a 24-bit PNG image with alpha channel transparency. See the guide for more. hasAlphaChannel defaults to false.

MapWindow

This class represents a window placed over the map.

Constructor

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 second optional argument is a hash of window options. They are (defaults are in parenthesis):

Property Default Description
alwaysOnTop false specifies if this window should always be on top of other windows
noEffect false specifies if window will appear with fade-in and fade-out effect
closeOnMove false specifies if this window will be closed when the map is dragged
bringToTop false specifies if this window will be brought to the top if other windows are clicked
width 252 specifies the width of the window in pixels
height 236 specifies the height of the window in pixels
padding 10 specifies the padding of the window in pixels

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 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).</nowiki>

The optional markerOptions argument is a MarkerOptions object that defaults to null.

MarkerOptions

Properties

Property Default 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 guide for more.

SLMap

This class represents the map.

Constructor

SLMap ( HTMLElement container, SLMapOptions options )

Creates the map. The SLMapOptions argument is optional.

Methods

Method Return Value Description

addMapWindow( MapWindow mapWindow, XYPoint coord )

None Adds a MapWindow to the map at specified coordinate.

addMarker( Marker marker, MapWindow mapWindow )

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

clickMarker( Marker marker)

None Simulates a clicking a marker. Will recenter 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.

enterAndZoomAtSLCoord( XYPoint coordinate, int zoom)

None Centers and zooms the map to the specified location.

getCurrentZoomLevel()

None Gets the current zoom level (1-6). See about zoom levels.

getMapCenter()

XYPoint Returns the current map center. See about coordinates.

getViewportBounds()

Bounds Gets the viewport bounds. See about coordinates.

panDown()

None Pans the map to the down by half its width.

panLeft()

None Pans the map to the left by 1/2 its width.

panOrRecenterToSLCoord( XYPoint coord, Boolean recenter )

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

panRight()

None Pans the map to the right by 1/2 its width.

panUp()

None Pans the map to the up by 1/2 its width.

removeAllMarkers()

None Removes all markers.

removeMarker( Marker marker)

None Removes a marker.

setCurrentZoomLevel( int zoom)

None Sets the zoom level to specified zoom.

zoomIn()

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

zoomOut()

None 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

Property Default 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 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 guide for more.

SLPoint

Not currently implemented.

XYPoint

Represents a point in 2D coordinate space.

Constructor

XYPoint ( Float x, Float y )

Creates an XYPoint object.

Properties

Property Default Description
x None X coordinate
y None Y coordinate