flutter_map Documentation

To run the demo application to explore flutter_map features, clone the repository to your local machine, connect a device or emulator, and execute the following commands in your terminal:

1. flutter clean
2. flutter run

Note that there are no pre-built versions available; you must run it from the source.

To customize the iOS launch screen, you can either replace the image files directly in the example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory or use Xcode.

To use Xcode:

1. Open the iOS project using open ios/Runner.xcworkspace.
2. In the Xcode Project Navigator, select Runner/Assets.xcassets.
3. Drag and drop your desired images into the asset catalog.

Configure how tiles are fetched using urlTemplate and additionalOptions. additionalOptions allows you to inject static values (like API keys) into the URL template placeholders.

Key Parameters:

• urlTemplate: A string containing placeholders like {z}, {x}, {y}, and {s} (subdomain).
• additionalOptions: A map of key-value pairs to replace placeholders in the urlTemplate.
• subdomains: A list of subdomains (e.g., ['a', 'b', 'c']) to be used with the {s} placeholder.
• fallbackUrl: A fallback template used if the primary urlTemplate fails. Note: using this disables in-memory caching to prevent mixed tilesets.

When enableMultiFingerGestureRace is set to true, multiple gestures can compete to become the active interaction. If multiple gestures reach their thresholds simultaneously, precedence is given in this order: pinchZoomWinGestures > rotationWinGestures > pinchMoveWinGestures.

To adjust this behavior, use:

• rotationThreshold: Degrees required to start rotation (default: 20.0).
• pinchZoomThreshold: Threshold to start zooming (default: 0.5).
• pinchMoveThreshold: Threshold to start moving via pinch (default: 40.0).
• rotationWinGestures: The MultiFingerGesture bitmask used when rotation wins.
• pinchZoomWinGestures: The MultiFingerGesture bitmask used when zoom wins.
• pinchMoveWinGestures: The MultiFingerGesture bitmask used when pinch-move wins.

Note: These only take effect if the corresponding InteractiveFlag is present in flags.

The abortObsoleteRequests option allows NetworkTileProvider to cancel in-flight HTTP requests for tiles that are no longer being displayed (e.g., when a user zooms quickly past a certain level).

Benefits:

• Improved tile loading speeds.
• Reduced network data consumption.
• Reduced storage usage in the cachingProvider.
• Reduced tile server costs.

Note: This functionality is most effective on web platforms (using BrowserClient) or with clients/servers that have limited simultaneous connections. If the provided httpClient does not support standard request aborting, this option will have no effect. It is recommended to keep this enabled unless issues arise.

Tiles are stored as files where the filename is the output of the cacheKeyGenerator (defaulting to a v5 UUID). The file contains a metadata header followed by the raw tile image bytes.

Header Structure:

1. Identifier (6 bytes): ASCII string FMBICT.
2. Version (2 bytes): Uint16 (currently 1).
3. staleAt (8 bytes): Int64 timestamp (milliseconds since Unix epoch, UTC).
4. lastModified (8 bytes): Int64 timestamp (milliseconds since Unix epoch, UTC). If not provided, use 0.
5. etag Length (2 bytes): Uint16 representing the length of the ASCII encoded etag.
6. etag (Variable): ASCII encoded string (max 65535 bytes). If not provided, 0 bytes.
7. Image Length (4 bytes): Uint32 representing the length of the tile image bytes following the header.

The size monitor is stored in a file named sizeMonitor.bin. It contains a single 8-byte unsigned integer (Uint64) representing the total size of all tiles and metadata in the cache in bytes.

Important behaviors:

• Synchronization: The monitor must stay in sync with the actual filesystem size. If a read failure occurs (suggesting corruption), the monitor must be disabled and recalculated on the next startup.
• Recalculation: Recalculation is an expensive I/O operation performed on startup. While calculating, writes must be delayed, but reads can still occur.

When using NetworkTileProvider on the web, be aware of the following limitations:

1. User-Agent Header: The User-Agent header cannot be modified due to Dart/browser limitations.
2. Request Cancellation: While supportsCancelLoading returns true, actual abortion of in-flight HTTP requests is not yet supported in Dart on the web. This means getImageWithCancelLoadingSupport cannot fully abort requests on web platforms.

To apply a constraint to a camera, call the constrain(MapCamera camera) method on a CameraConstraint instance.

Note: The method returns a nullable MapCamera?. It returns null if no appropriate camera could be generated by the movement (for example, if the camera is zoomed out too far to satisfy the constraint).