{"id":18234160,"url":"https://github.com/trademe/mapme","last_synced_at":"2025-04-12T18:45:18.512Z","repository":{"id":39618157,"uuid":"98249217","full_name":"TradeMe/MapMe","owner":"TradeMe","description":"The Android maps adapter","archived":false,"fork":false,"pushed_at":"2022-03-30T20:42:56.000Z","size":823,"stargazers_count":841,"open_issues_count":12,"forks_count":76,"subscribers_count":37,"default_branch":"master","last_synced_at":"2025-04-03T20:13:16.540Z","etag":null,"topics":["diffutil","googlemaps","kotlin","kotlin-android","mapbox","maps","markers","recyclerview"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TradeMe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2017-07-25T01:14:06.000Z","updated_at":"2025-03-11T05:46:01.000Z","dependencies_parsed_at":"2022-09-16T11:32:16.463Z","dependency_job_id":null,"html_url":"https://github.com/TradeMe/MapMe","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FMapMe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FMapMe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FMapMe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FMapMe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TradeMe","download_url":"https://codeload.github.com/TradeMe/MapMe/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248617343,"owners_count":21134190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diffutil","googlemaps","kotlin","kotlin-android","mapbox","maps","markers","recyclerview"],"created_at":"2024-11-04T18:03:54.749Z","updated_at":"2025-04-12T18:45:18.488Z","avatar_url":"https://github.com/TradeMe.png","language":"Kotlin","readme":"# MapMe\n\n![MapMe](./img/feature.png)\n\n[ ![Download](https://api.bintray.com/packages/trademe/MapMe/mapme/images/download.svg) ](https://bintray.com/trademe/MapMe/mapme/_latestVersion)\n[![Build Status](https://travis-ci.org/TradeMe/MapMe.svg?branch=master)](https://travis-ci.org/TradeMe/MapMe)\n\nMapMe is an Android library for working with Maps. MapMe brings the adapter pattern to Maps, simplifying the management of markers and annotations.\n\nMapMe supports both [Google Maps](https://developers.google.com/maps/documentation/android-api/) and [Mapbox](https://www.mapbox.com/android-sdk/)\n\n\nDownload\n-----\n\n```groovy\n//base dependency\ncompile 'nz.co.trademe.mapme:mapme:1.2.1'\n  \n//for Google Maps support\ncompile 'nz.co.trademe.mapme:googlemaps:1.2.1'\n  \n//for Mapbox support\ncompile 'nz.co.trademe.mapme:mapbox:1.2.1'\n\n```\n\nUsage\n-----\nA simple MapsAdapter might look like this:\n\n```kotlin\nclass MapsAdapter(context: Context, private val markers: List\u003cMarkerData\u003e) : GoogleMapMeAdapter(context) {\n\n    fun onCreateAnnotation(factory: AnnotationFactory, position: Int, annotationType: Int): MapAnnotation {\n        val item = this.markers[position]\n        return factory.createMarker(item.getLatLng(), null, item.getTitle())\n    }\n\n    fun onBindAnnotation(annotation: MapAnnotation, position: Int, payload: Any) {\n        if (annotation is MarkerAnnotation) {\n            val item = this.markers[position]\n            annotation.setTitle(item.getTitle())\n        }\n    }\n\n    val itemCount: Int\n        get() = markers.size()\n}\n\n```\n\nUsing the adapter in your view:\n\n```kotlin\nval adapter: MapMeAdapter = GoogleMapMeAdapter(context, items)\nadapter.setOnAnnotationClickListener(this)\n\nmapView.getMapAsync { googleMap -\u003e\n    //Attach the adapter to the map view once it's initialized\n    adapter.attach(mapView, googleMap)\n}\n```\n\nDispatch data updates to the adapter:\n\n```kotlin\n// add new data and tell the adapter about it\n\nitems.addAll(myData)\nadapter.notifyDataSetChanged()\n\n// or with DiffUtil\n\nval diff = DiffUtil.calculateDiff(myDiffCallback)\ndiff.dispatchUpdatesTo(adapter)\n```\n\n\nClick listeners\n-----\nMapMe takes the pain out of click listeners too. No more setting tags on markers and trying to match a tag to your data when the click event is received.\n\nMapMe has a `setOnAnnotationClickListener` method that will pass back a `MapAnnotation` containing the position of the item in the list of data:\n\n```Kotlin\nmapsAdapter.setOnAnnotationClickListener(OnMapAnnotationClickListener { annotation -\u003e\n            //retrieve the data item based on the position\n            val item = myData[annotation.position]\n            \n            //handle item click here\n            \n            true\n        })\n\n```\n\n**Info window** clicks are handled in the same way.\n\nAnimations\n-----\n\nWhile MapMe doesn't handle marker animations directly, it does provide a `onAnnotationAdded` method on the adapter that is called when a marker is added to the map.\n\nThis is the ideal place to start an animation.\n\n\nFor example, the following animates a markers alpha when it is added to the map:\n\n\n```\noverride fun onAnnotationAdded(annotation: MapAnnotation) {\n        if (annotation !is MarkerAnnotation) return\n\n        ObjectAnimator.ofFloat(annotation, \"alpha\", 0f, 1f)\n                .apply {\n                    duration = 150\n                    interpolator = DecelerateInterpolator()\n                    start()\n               }\n}\n```  \n    \n\nMarkers and Annotations\n-----\nMapMe is based around the concept of Annotations. An annotation is anything displayed on the map.\n\nThe only annotation currently supported is Markers. We hope to support many more in the future.\n\n*We'd love PR's adding support for more annotations!*\n\n\n### Multiple annotation types\nMore complex adapters can override `getItemAnnotationType` to work with multiple annotations. The annotation type is passed to `onCreateAnnotation` just like in a RecyclerView Adapter.\n\n\n### AnnotationFactory\nMapMe differs from list adapters in that the creation of annotations must be left up to the map as they are not standard Android views.\n\nThe MapAdapter **onCreateAnnotation** method provides an **AnnotationFactory** as a parameter that must be used to create and return Map Annotations.\n\n\nDiffUtil\n-----\nAs well as support for standard Adapter methods such as *notifyDataSetChanged*, and *notifyItemInserted*, MapMe supports (and recommends) DiffUtil.\n\nDiffUtil is where the true power of MapMe comes into play. Simple manipulate the data set, calculate the diff and dispatch it to MapMe. The map will instantly reflect the data.\n\nA DiffResult can be dispatched to the MapAdapter just as you would a RecyclerView:\n\n```java\nDiffUtil.DiffResult diffResult = DiffUtil.calculateDiff(new MarkerDiffCallback(this.markers, newMarkers));\ndiffResult.dispatchUpdatesTo(mapAdapter);\n```\n\n\nWhy the adapter pattern?\n-----\n\nWorking with a few map markers is simple, but working with hundreds can become a mess of spaghetti code. \n\nThe adapter pattern provides a clear separation of data from the view, allowing the data to be manipulated freely without the concern of updating the view.\n\nWe think this is a pattern fits perfectly with maps.\n\n\n## Contributing\n\nWe love contributions, but make sure to checkout `CONTRIBUTING.MD` first!\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrademe%2Fmapme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrademe%2Fmapme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrademe%2Fmapme/lists"}