mergMK is a LiveCode MapKit external that adds a map control which supports showing user location with heading, adding annotation pins and polylines. Create stunning interactive maps with ease. Important: The Map Kit framework uses Google services to provide map data pre-iOS 6. Use of specific classes of this framework (and their associated interfaces) binds you to the Google Maps/Google Earth API terms of service. You can find these terms of service at https://code.google.com/apis/maps/iphone/terms.html.
command mergMKCreate
This command initialises/creates the map but does not display it. It must be called after the stack is open so if opening an app to a map you would need to send this command after openStack is complete. The external retains a reference to the control that called this command (the control reference equivalent to "me" when calling the command) and sends any callbacks to it.
command mergMKDelete
This command deletes the current map and removes it from the screen if it's currently visible.
command mergMKSet pProperty,pValue,[pAnimated]
Set the properties of the map.
Parameters:
- pProperty - The property to set. One of:
- rect - a standard rect string in livecode (left,top,right,bottom)
- visible - true or false
- center coordinate - a location in decimal coordinates (latitude,longitude)
- region - the width,height in metres to display within the map
- shows user location - true or false
- scroll enabled - true or false
- user tracking mode - (iOS 5.0+) one of:
- none
- follow
- follow with heading
- zoom enabled - true or false
- map type - map type - one of:
- standard
- hybrid
- satellite
- pValue - The value to set the property.
- pAnimated - (optional with "false" default) true or false with true as default is applicable to the following properties:|center coordinate|region|user tracking mode
- false
- true
Code sample
mergMKSet "rect",the rect of me put iphoneCurrentLocation() into tLocation mergMKSet "center coordinate", (tLocation["latitude"],tLocation["longitude"]) mergMKSet "visible",true |
function mergMKGet pProperty
Get a map property
Parameters:
- pProperty -
- rect - a standard rect string in livecode (left,top,right,bottom)
- visible - true or false
- center coordinate - a location in decimal coordinates (latitude,longitude)
- region - the width,height in metres to display within the map
- shows user location - true or false
- scroll enabled - true or false
- user tracking mode - (iOS 5.0+) one of:
- none
- follow
- follow with heading
- zoom enabled - true or false
- map type - map type - one of:
- standard
- hybrid
- satellite
Returns The value of the property.
Code sample
put mergMKGet("center coordinate") into tSaveLoc |
Notifications
message mergMKUserLocationChanged pCoordinate
This message is sent to the object that created the map control when the user's location is updated on the map.
Parameters:
- pCoordinate - a location in decimal coordinates (latitude,longitude)
message mergMKRegionChanged pRegion
This message is sent to the object that created the map control when the map region is changed either by the user or by script. When setting the region a best fit occurs to show the specified region.
Parameters:
- pRegion - a region width and height in metres
message mergMKMapLoaded
This message is sent to the object that created the map control when the map is loaded
message mergMKUserTrackingModeChanged pTrackingMode
This message is sent to the object that created the map control when the user tracking mode is changed
Parameters:
- pTrackingMode - one of:|none|follow|follow with heading
Annotations
function mergMKAddAnnotation pCoordinate,pTitle,[pSubtitle],[pShowCallout],[pAnimateDrop],[pPinColor],[pDraggable],[pCalloutImage],[pShowCalloutButton]
Returns an id for the annotation that was created. The id will be included as a parameter in annotation interaction callback messages.
Parameters:
- pCoordinate - a location in decimal coordinates (latitude,longitude)
- pTitle - the title for the annotation (shown on the callout)
- pSubtitle - (optional with "" default) the subtitle for the annotation (shown on the callout)
- pShowCallout - (optional with "true" default) true or false to show the callout when the user touches the annotation with true as default
- false
- true
- pAnimateDrop - (optional with "true" default) true or false to animate the annotation drop with true as default
- false
- true
- pPinColor - (optional with "red" default) one of:|red (default)|purple|green
- red
- purple
- green
- pDraggable - (optional with "false" default) true or false to enable drag and drop with false as default
- false
- true
- pCalloutImage - (optional with optionally default) optionally add an image to the left side of the accessory view (32x32)
- pShowCalloutButton - (optional with "true" default) true or false to show the button on the right of the callout
- false
- true
Returns The ID of the annotation.
Code sample
put mergMKAddAnnotation(mergMKGet("center coordinate"),"Dig Here!") into tAnnotationID |
function mergMKAddAnnotationWithImage pCoordinate,pTitle,pImage,[pSubtitle],[pShowCallout],[pAnimateDrop],[pDraggable],[pImageCenterOffset],[pCalloutImage],[pShowCalloutButton]
Returns an id for the annotation that was created. The id will be included as a parameter in annotation interaction callback messages.
Parameters:
- pCoordinate - a location in decimal coordinates (latitude,longitude)
- pTitle - the title for the annotation (shown on the callout)
- pImage - An image to use as a pin. The image will be centered on the coordinate.
- pSubtitle - (optional with "" default) the subtitle for the annotation (shown on the callout)
- pShowCallout - (optional with "true" default) true or false to show the callout when the user touches the annotation with true as default
- false
- true
- pAnimateDrop - (optional with "true" default) true or false to animate the annotation drop with true as default
- false
- true
- pDraggable - (optional with "false" default) true or false to enable drag and drop with false as default
- false
- true
- pImageCenterOffset - (optional with "0,0" default) By default, the center point of an annotation view is placed at the coordinate point of the associated annotation. You can use this property to reposition the annotation view as needed. This x and y offset values are measured in pixels. Positive offset values move the annotation view down and to the right, while negative values move it up and to the left.
- pCalloutImage - (optional with optionally default) optionally add an image to the left side of the accessory view
- pShowCalloutButton - (optional with "true" default) true or false to show the button on the right of the callout
- false
- true
Returns The ID of the annotation.
command mergMKDeleteAnnotation pAnnotationID
This command deletes the annotation from the map.
Parameters:
- pAnnotationID - An annotation ID as returned by mergMKAddAnnotation
command mergMKAnnotationSet pAnnotationID,pProperty,pValue
Set individual annotation properties
Parameters:
- pAnnotationID - An annotation ID as returned by mergMKAddAnnotation
- pProperty -
- coordinate
- title
- image
- pin color
- subtitle
- show callout
- draggable
- center offset
- callout image
- show callout button
- selected
- pValue - The value to set the annotation property to
function mergMKAnnotationGet pAnnotationID,pProperty
Get individual annotation properties
Parameters:
- pAnnotationID - An annotation ID as returned by mergMKAddAnnotation
- pProperty -
- coordinate
- title
- image
- pin color
- subtitle
- show callout
- draggable
- center offset
- callout image
- show callout button
- selected
Returns The value of the annotation property
message mergMKAnnotationCalloutTapped pAnnotationID
This message is sent to the object that created the map control when the user touches on the callout disclosure icon of an annotation.
Parameters:
- pAnnotationID - An annotation ID as returned by mergMKAddAnnotation
message mergMKAnnotationSelected pAnnotationID
This message is sent to the object that created the map control when the user touches an annotation.
Parameters:
- pAnnotationID - An annotation ID as returned by mergMKAddAnnotation
message mergMKAnnotationDeselected pAnnotationID
This message is sent to the object that created the map control when an annotation pin is deselected (user touches somewhere else).
Parameters:
- pAnnotationID - An annotation ID as returned by mergMKAddAnnotation
message mergMKAnnotationDropped pAnnotationID,pCoordinate
This message is sent to the object that created the map control when an annotation pin is dragged and dropped to a new location.
Parameters:
- pAnnotationID - An annotation ID as returned by mergMKAddAnnotation
- pCoordinate - a location in decimal coordinates (latitude,longitude)
Overlays
function mergMKAddPolylineOverlay pCoordinates,[pLineWidth],[pLineColor]
Returns an id for the overlay that was created.
Parameters:
- pCoordinates - a list of locations (one per line) in decimal coordinates (latitude,longitude)
- pLineWidth - (optional with 3 default) the width of the line in points defaults to 3
- pLineColor - (optional with "0,0,0,0" default) the color of the line defaults to opaque red. The string is an RGB value with each color component an integer between 0 and 255. An optional fourth item between 0 and 255 may be included to represent the alpha transparency.
Returns The overlay ID.
Code sample
put mergMKAddPolylineOverlay(tTrack,3,"0,255,0,100") into tOverlayID |
function mergMKAddPolygonOverlay pCoordinates,[pLineWidth],[pLineColor],[pFillColor]
Returns an id for the overlay that was created.
Parameters:
- pCoordinates - a list of locations (one per line) in decimal coordinates (latitude,longitude)
- pLineWidth - (optional with 3 default) the width of the line in points defaults to 3
- pLineColor - (optional with "0,0,0,0" default) the color of the line defaults to opaque red. The string is an RGB value with each color component an integer between 0 and 255. An optional fourth item between 0 and 255 may be included to represent the alpha transparency.
- pFillColor - (optional with "0,0,0,255" default) the color of the line defaults to opaque red. The string is an RGB value with each color component an integer between 0 and 255. An optional fourth item between 0 and 255 may be included to represent the alpha transparency.
Returns The overlay ID.
Code sample
put mergMKAddPolygonOverlay(tCarpark,3,"0,255,0,100","0,255,0,150") into tOverlayID |
function mergMKAddCircleOverlay pCoordinate,pRadius,[pLineWidth],[pLineColor],[pFillColor]
Returns an id for the overlay that was created.
Parameters:
- pCoordinate - the center of the circle in decimal coordinates (latitude,longitude)
- pRadius - the radius of the circle in metres
- pLineWidth - (optional with 3 default) the width of the line in points defaults to 3
- pLineColor - (optional with "0,0,0,0" default) the color of the line defaults to opaque red. The string is an RGB value with each color component an integer between 0 and 255. An optional fourth item between 0 and 255 may be included to represent the alpha transparency.
- pFillColor - (optional with "0,0,0,255" default) the color of the line defaults to opaque red. The string is an RGB value with each color component an integer between 0 and 255. An optional fourth item between 0 and 255 may be included to represent the alpha transparency.
Returns The overlay ID.
Code sample
put mergMKAddCircleOverlay(tPicnicArea,20,3,"0,255,0,100","0,255,0,150") into tOverlayID |
command mergMKDeleteOverlay pOverlayID
This command deletes the overlay from the map. The only overly currently implemented is polyline but there is scope for more.
Parameters:
- pOverlayID - An overlay ID as returned by mergMKAddPolylineOverlay and mergMKAddPolygonOverlay.
Directions
command mergMKGetDirections pFromCoordinate,pToCoordinate
Get directions between two coordinates
Parameters:
- pFromCoordinate - the from coordinate in decimal coordinates (latitude,longitude)
- pToCoordinate - the to coordinate in decimal coordinates (latitude,longitude)
message mergMKDirectionsError pFromCoordinate,pToCoordinate,pError
This message is sent to the object that called mergMKGetDirections when there is an error determining directions
Parameters:
- pFromCoordinate - the from coordinate in decimal coordinates (latitude,longitude)
- pToCoordinate - the to coordinate in decimal coordinates (latitude,longitude)
- pError - the error message
message mergMKDirections pFromCoordinate,pToCoordinate,pDirectionsID,pRoutes
This message is sent to the object that called mergMKGetDirections when directions have been determined
Parameters:
- pFromCoordinate - the from coordinate in decimal coordinates (latitude,longitude)
- pToCoordinate - the to coordinate in decimal coordinates (latitude,longitude)
- pDirectionsID - the id of the directions
- pRoutes - the number of routes found
command mergMKDirectionsDelete pDirectionID
Delete the directions
Parameters:
- pDirectionID - A directions ID as returned by the mergMKDirections message
command mergMKDirectionsAddPolylineOverlay pDirectionID,pRouteNumber,[pStepNumber],[pLineWidth],[pLineColor]
Add a polyline overlay showing the directions for a route or a step within a route
Parameters:
- pDirectionID - A directions ID as returned by the mergMKDirections message
- pRouteNumber - A route number between 1 and the number of routes sent in the mergMKDirections message
- pStepNumber - (optional with 0 default) The step number within the route. If you want to draw the entire route polyline then set this parameter to 0
- pLineWidth - (optional with 3 default) the width of the line in points defaults to 3
- pLineColor - (optional with "0,0,0,0" default) the color of the line defaults to opaque red. The string is an RGB value with each color component an integer between 0 and 255. An optional fourth item between 0 and 255 may be included to represent the alpha transparency.
Sets the result to the overlay id as required by mergMKDeleteOverlay
function mergMKDirectionsRouteGet pDirectionID,pRouteNumber,pProperty
Get a property of a directions route
Parameters:
- pDirectionID - A directions ID as returned by the mergMKDirections message
- pRouteNumber - A route number between 1 and the number of routes sent in the mergMKDirections message
- pProperty - A route property
- name - The string in this property is localized according to the user’s language preferences. You can display this string to the user from your app’s user interface so that the user can distinguish one route from another. The string itself describes the route using one of the route’s significant features. For example, a route that uses a major highway for a significant portion of the route might use that highway for its name.
- distance - The distance of the route.
- steps - The number of steps in the route.
- transport type - This property reflects the primary transport type used for the route. Individual steps of the route might use different transport types. One of: automobile
- walking
- any
- expected travel time - This expected travel time reflects the time it takes to traverse the route under ideal conditions. The actual amount of time may vary based on conditions.
- advisory notices - This property contains additional information that is important for the user to know about the route. For example, it might note that a portion of the route is closed during the winter or after big storms.
Returns The property value
function mergMKDirectionsRouteStepGet pDirectionID,pRouteNumber,pStepNumber,pProperty
Get a property of a directions route step
Parameters:
- pDirectionID - A directions ID as returned by the mergMKDirections message
- pRouteNumber - A route number between 1 and the number of routes sent in the mergMKDirections message
- pStepNumber - The step number within the route.
- pProperty - A route property
- instructions - The written instructions for following the path represented by this step.
- notice - Notices may include legal information or warning notices that apply to the step. For example, if the step crosses railroad tracks, it might contain a notice that warns the user not to cross the tracks when the lights are flashing.
- distance - The distance of the route.
- transport type - This property reflects the primary transport type used for the route. Individual steps of the route might use different transport types. One of: automobile
- walking
- any
Returns The property value