mergMK

Screenshot_28 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