Instance Method

showItems

Adjusts the maps visible region to bring the specified overlays and annotations into view.

Declaration

mapkit.Annotation|mapkit.Overlay[] showItems(mapkit.Annotation|mapkit.Overlay[] items, optional MapShowItemsOptions options);

Parameters

items

An array of annotations and/or overlays to make visible.

options

Options defined by MapShowItemsOptions that let you determine animation, padding, and the minimum span.

Return Value

Returns the items array that was passed in.

Discussion

Adjusts the map's region to bring the specified items into view. An item is an annotation or overlay. The items are added to the map if they are not already in the map.

The region will cover the smallest longitudinal span possible. For example, consider an array of items that consists of two annotations for the cities Tokyo and Los Angeles, and a polyline that represents the flight path between them. The region chosen will cover the Pacific Ocean rather than North America, the Atlantic Ocean, Europe and Asia.

In deciding how much to show, this method takes the actual pixel size of the items into account. For example, even though an annotation represents a point, the annotation itself occupies space. This method ensures that the entirety of an annotation is visible in the map. Similarly, this method ensures that an overlay with thick lines is shown in its entirety.

However, in some cases it is possible that not all items can be shown at once, or the actual padding does not match the requested padding. This happens if:

  • One or more items falls outside of the visible map region that can be displayed, even at the minimum zoom level.

  • The amount of padding is determined by the zoom level, which always snaps to an integral zoom level and may have a different amount of padding than requested.

Exceptions

This method throws an Error if the arguments to the method are invalid.

Example Usage

var park = new mapkit.MarkerAnnotation(new mapkit.Coordinate(37.749581, -119.524212), { title: "Yosemite" }),
    surf = new mapkit.MarkerAnnotation(new mapkit.Coordinate(37.49557, -122.496687), { title: "Mavericks" });
map.showItems([park, surf],
              { animate: true,
                padding: new mapkit.Padding(60, 25, 60, 25)
              });  

See Also

Configuring the Map's Appearance

colorScheme

The map’s color scheme when displaying standard or muted standard map types.

distances

The system of measurement displayed on the map.

mapType

The type of data displayed by the map view.

padding

The map's inset margins.

showsCompass

A feature visibility setting that determines when the compass is visible.

showsMapTypeControl

A Boolean value that determines whether to display a control that lets users choose the map type.

showsZoomControl

A Boolean value that determines whether to display a control for zooming in and zooming out on a map.

showsUserLocationControl

A Boolean value that determines whether the user location control is visible.

showsPointsOfInterest

A Boolean value that determines whether the map displays points of interest.

showsScale

A feature visibility setting that determines when the map's scale is displayed.

tintColor

The CSS color that is used to paint the user interface controls on the map.

MapShowItemsOptions

Options that determine map parameters used when showing items.