From 80069e1acb8e3b8d195a568e35eed8380b3667f3 Mon Sep 17 00:00:00 2001 From: Alexander Borsuk Date: Sun, 5 Jun 2022 15:56:20 +0200 Subject: [PATCH] Updated API example Signed-off-by: Alexander Borsuk --- README.html | 174 ------------------ README.md | 80 ++++---- lib/AndroidManifest.xml | 4 +- lib/res/layout/dlg_install_mwm.xml | 4 +- lib/res/values/strings.xml | 8 +- lib/src/com/mapswithme/maps/api/Const.java | 18 +- .../maps/api/DownloadMapsWithMeDialog.java | 12 +- lib/src/com/mapswithme/maps/api/MWMPoint.java | 27 ++- .../com/mapswithme/maps/api/MWMResponse.java | 32 ++-- .../mapswithme/maps/api/MapsWithMeApi.java | 34 ++-- .../com/mapswithme/maps/api/MwmRequest.java | 24 +-- readme_to_html.sh | 11 -- sample-app-capitals/AndroidManifest.xml | 4 +- .../res/layout/capitals_list_activity.xml | 2 +- .../res/layout/city_details_activity.xml | 4 +- .../capitals/CapitalsListActivity.java | 18 +- .../src/com/mapswithme/capitals/City.java | 8 +- .../capitals/CityDetailsActivity.java | 20 +- 18 files changed, 153 insertions(+), 331 deletions(-) delete mode 100644 README.html delete mode 100755 readme_to_html.sh diff --git a/README.html b/README.html deleted file mode 100644 index f22c6e3..0000000 --- a/README.html +++ /dev/null @@ -1,174 +0,0 @@ -

maps.me Android API: Getting Started

- -

Introduction

- -

NOTE: We have changed the name of our maps from MapsWithMe to MAPS.ME, but left all references below unchanged.

- -

MapsWithMe Android API (hereinafter referred to as "API Library" or just "library") -provides interface for client application to perform next tasks:

- - - -

Thus, you can provide two way communication between your application and MapsWithMe, -using MapsWithMe to show points of interest (POI) and providing more information in your app.

- -

Please refer to sample application for demo or see -our travel guide apps as an API integration example.

- -

Prerequisites

- -

It is supposed that you are familiar with Android Development, and you have Android SDK and Eclipse (or another IDE of your choice) installed. -You should be familiar with concept of Intents, library projects, and PendingIntents (recommended) as well. -Your application must target at least android sdk version 9.

- -

Integration

- -

First step is to clone repository or download it as an archive.

- -

When your are done you find two folders: lib and sample-app-capitals. First one is a library project that you should add to your project. -You don't need any additional permissions in your AndroidManifest.xml to use API library, so you can write real code straight away, calling for different MapsWithMeApi methods (more details below).

- -

Classes Overview and HOW TO

- -

Core classes you will work with are:

- - - -

Show Points on the Map

- -

The simplest usage:

- -
public class MyPerfectActivity extends Activity {
-...
-
-  void showSomethingOnTheMap(SomeDomainObject arg)
-  {
-    // Do some work, create lat, lon, and name for point
-    final double lat = ...;
-    final double lon = ...;
-    final String name = ...;
-    // Ask MapsWithMe to show the point
-    MapsWithMeApi.showPointOnMap(this, lat, lon, name);
-  }
-...
-
-}
-
- -

For multiple points use MWMPoint class:

- -
void showMultiplePoints(List<SomeDomainObject> list)
-{
-  // Convert objects to MMWPoints
-  final MWMPoint[] points = new MWMPoint[list.length];
-  for (int i = 0; i < list.size; i++)
-  {
-    // Get lat, lon, and name from object and assign it to new MMWPoint
-    points[i] = new MWMPoint(lat, lon, name);
-  }
-  // Show all point on the map, you could also provide some title
-  MapsWithMeApi.showPointsOnMap(this, "Look at my points, my points are amazing!", points);
-}
-
- -

Ask MapsWithMe to Call my App

- -

We support PendingIntent interaction (just like Android native -NotificationManager does). You should specify ID for each point to -distinguish it later, and PentingIntent that MapsWithMe will send back to -your application when user press "More Info" button :

- -
// Here is how to pass points with ID ant PendingIntent
-void showMultiplePointsWithPendingIntent(List<SomeDomainObject> list, PendingIntent pendingIntent)
-{
-  // Convert objects to MWMPoints
-  final MWMPoint[] points = new MWMPoint[list.length];
-  for (int i = 0; i < list.size; i++)
-  {
-    //                                      ||
-    //                                      ||
-    //                                      \/
-    //         Now you should specify string ID for each point
-    points[i] = new MWMPoint(lat, lon, name, id);
-  }
-  // Show all points on the map, you could also provide some title
-  MapsWithMeApi.showPointsOnMap(this, "This title says that user should choose some point", pendingIntent, points);
-}
-
-//Code below shows general way to extract response data
-@Override
-protected void onCreate(Bundle savedInstanceState) {
-    super.onCreate(savedInstanceState);
-    setContentView(R.layout.activity_main);
-    // Handle intent you specified with PandingIntent
-    // Now it has additional information (MWMPoint).
-    handleIntent(getIntent());
-}
-
-@Override
-protected void onNewIntent(Intent intent)
-{
-  super.onNewIntent(intent);
-  // if defined your activity as "SingleTop"- you should use onNewIntent callback
-  handleIntent(intent);
-}
-
-void handleIntent(Intent intent)
-{
-  // Apply MWMResponse extraction method to intent
-  final MWMResponse mwmResponse = MWMResponse.extractFromIntent(this, intent);
-  // Here is your point that user selected
-  final MWMPoint point = mwmResponse.getPoint();
-  // Now, for instance you can do some work depending on point id
-  processUserInteraction(point.getId());
-}
-
- -

FAQ

- -

How should I detect if user has MapsWithMe installed?

- -

MapsWithMeApi.isMapsWithMeInstalled(Context) will return true if user has Lite or Pro version that supports API call installed.

- -

Which versions of MapsWithMe support API calls?

- -

All versions since 2.4.0 and above support API calls.

- -

What will happen if I call for MapsWithMeApi.showPoint() but MapsWithMe application is not installed?

- -

Nothing serious. API library will show simple dialog with gentle offer to download MapsWithMe. You can see how it looks like below. Please install us

- -

Sample Code and Application

- - - -

Support

- -

If you have any questions please email to api@mapswith.me.

- -
- -

API Code License

- -

Copyright (c) 2014, MapsWithMe GmbH -All rights reserved.

- -

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- - - -

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

diff --git a/README.md b/README.md index 9788368..7eaa260 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,38 @@ -# maps.me Android API: Getting Started +# Organic Maps Android API: Getting Started ## Introduction -NOTE: We have changed the name of our maps from MapsWithMe to MAPS.ME, but left all references below unchanged. - -MapsWithMe Android API (hereinafter referred to as *"API Library"* or just *"library"*) +Organic Maps Android API (hereinafter referred to as *"API Library"* or just *"library"*) provides interface for client application to perform next tasks: -* Show one or more points on offline map of [MapsWithMe Application][linkMwm] -* Come back to the client application after selecting specific point on the map, by sending [PendingIntent][linkPIntent] with point data when user asks for more information by pressing "More Info" button in MapsWithMe Application +* Show one or more points on offline map of [Organic Maps app][linkOM] +* Come back to the client application after selecting specific point on the map, by sending [PendingIntent][linkPIntent] with point data when user asks for more information by pressing "More Info" button in Organic Maps app * Map screen branding : your application's icon and name (or custom title) will be placed at the top. -Thus, you can provide **two way communication between your application and MapsWithMe**, -using MapsWithMe to show points of interest (POI) and providing more information in your app. +Thus, you can provide **two way communication between your application and Organic Maps**, +using Organic Maps to show points of interest (POI) and providing more information in your app. -Please refer to [sample application][linkSampleSource] for demo or see -our [travel guide apps][linkTravelGuides] as an API integration example. +Please refer to [sample application][linkSampleSource] for demo. ## Prerequisites -It is supposed that you are familiar with Android Development, and you have Android SDK and Eclipse (or another IDE of your choice) installed. +It is supposed that you are familiar with Android Development. You should be familiar with concept of [Intents][linkIntents], [library projects][linkLibProj], and [PendingIntents][linkPIntent] (recommended) as well. -Your application must target at least *android sdk version 9*. + +Organic Maps works from *Android SDK version 21 (Android 5)* and above ## Integration First step is to clone [repository][linkRepo] or download it as an archive. When your are done you find two folders: *lib* and *sample-app-capitals*. First one is a library project that you should add to your project. -You don't need any additional permissions in your AndroidManifest.xml to use API library, so you can write real code straight away, calling for different `MapsWithMeApi` methods (more details below). +You don't need any additional permissions in your AndroidManifest.xml to use API library, so you can write real code straight away, calling for different `OrganicMapsApi` methods (more details below). ## Classes Overview and HOW TO Core classes you will work with are: -* [com.mapswithme.maps.api.MapsWithMeApi][linkApiClass] - static class with methods such as `showPointOnMap(Activity, double, double, String)` etc. -* [com.mapswithme.maps.api.MWMPoint][linkPointClass] - model of POI, includes lat, lon, name, id, and style data. -* [com.mapswithme.maps.api.MWMResponse][linkRespClass] - helps you to extract response from MapsWithMe by applying `MWMResponse.extractFromIntent(Intent)` to Intent. Contains MWMPoint data. +* [app.organicmaps.api.OrganicMapsApi][linkApiClass] - static class with methods such as `showPointOnMap(Activity, double, double, String)` etc. +* [app.organicmaps.api.OMPoint][linkPointClass] - model of POI, includes lat, lon, name, id, and style data. +* [app.organicmaps.api.OMResponse][linkRespClass] - helps you to extract response from Organic Maps by applying `OMResponse.extractFromIntent(Intent)` to Intent. Contains OMPoint data. ### Show Points on the Map @@ -49,51 +47,51 @@ The simplest usage: final double lat = ...; final double lon = ...; final String name = ...; - // Ask MapsWithMe to show the point - MapsWithMeApi.showPointOnMap(this, lat, lon, name); + // Ask Organic Maps to show the point + OrganicMapsApi.showPointOnMap(this, lat, lon, name); } ... } -For multiple points use [MWMPoint][linkPointClass] class: +For multiple points use [OMPoint][linkPointClass] class: void showMultiplePoints(List list) { // Convert objects to MMWPoints - final MWMPoint[] points = new MWMPoint[list.length]; + final OMPoint[] points = new OMPoint[list.length]; for (int i = 0; i < list.size; i++) { // Get lat, lon, and name from object and assign it to new MMWPoint - points[i] = new MWMPoint(lat, lon, name); + points[i] = new OMPoint(lat, lon, name); } // Show all point on the map, you could also provide some title - MapsWithMeApi.showPointsOnMap(this, "Look at my points, my points are amazing!", points); + OrganicMapsApi.showPointsOnMap(this, "Look at my points, my points are amazing!", points); } -### Ask MapsWithMe to Call my App +### Ask Organic Maps to Call my App We support PendingIntent interaction (just like Android native NotificationManager does). You should specify ID for each point to -distinguish it later, and PentingIntent that MapsWithMe will send back to +distinguish it later, and PentingIntent that Organic Maps will send back to your application when user press "More Info" button : // Here is how to pass points with ID ant PendingIntent void showMultiplePointsWithPendingIntent(List list, PendingIntent pendingIntent) { - // Convert objects to MWMPoints - final MWMPoint[] points = new MWMPoint[list.length]; + // Convert objects to OMPoints + final OMPoint[] points = new OMPoint[list.length]; for (int i = 0; i < list.size; i++) { // || // || // \/ // Now you should specify string ID for each point - points[i] = new MWMPoint(lat, lon, name, id); + points[i] = new OMPoint(lat, lon, name, id); } // Show all points on the map, you could also provide some title - MapsWithMeApi.showPointsOnMap(this, "This title says that user should choose some point", pendingIntent, points); + OrganicMapsApi.showPointsOnMap(this, "This title says that user should choose some point", pendingIntent, points); } //Code below shows general way to extract response data @@ -102,7 +100,7 @@ your application when user press "More Info" button : super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // Handle intent you specified with PandingIntent - // Now it has additional information (MWMPoint). + // Now it has additional information (OMPoint). handleIntent(getIntent()); } @@ -116,24 +114,24 @@ your application when user press "More Info" button : void handleIntent(Intent intent) { - // Apply MWMResponse extraction method to intent - final MWMResponse mwmResponse = MWMResponse.extractFromIntent(this, intent); + // Apply OMResponse extraction method to intent + final OMResponse mwmResponse = OMResponse.extractFromIntent(this, intent); // Here is your point that user selected - final MWMPoint point = mwmResponse.getPoint(); + final OMPoint point = mwmResponse.getPoint(); // Now, for instance you can do some work depending on point id processUserInteraction(point.getId()); } ## FAQ -#### How should I detect if user has MapsWithMe installed? -`MapsWithMeApi.isMapsWithMeInstalled(Context)` will return `true` if user has *Lite* or *Pro* version that supports API call installed. +#### How should I detect if user has Organic Maps installed? +`OrganicMapsApi.isOrganicMapsInstalled(Context)` will return `true` if user has *Lite* or *Pro* version that supports API call installed. -#### Which versions of MapsWithMe support API calls? +#### Which versions of Organic Maps support API calls? All versions since 2.4.0 and above support API calls. -#### What will happen if I call for `MapsWithMeApi.showPoint()` but MapsWithMe application is not installed? -Nothing serious. API library will show simple dialog with gentle offer to download MapsWithMe. You can see how it looks like below. +#### What will happen if I call for `OrganicMapsApi.showPoint()` but Organic Maps application is not installed? +Nothing serious. API library will show simple dialog with gentle offer to download Organic Maps. You can see how it looks like below. ![Please install us](site/images/dlg.png) @@ -154,14 +152,14 @@ Redistribution and use in source and binary forms, with or without modification, THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -[linkMwm]: https://maps.me/ "MAPS.ME" +[linkOM]: https://organicmaps.app/ "Organic Maps" [linkPIntent]: http://developer.android.com/reference/android/app/PendingIntent.html "PendingIntent" [linkRepo]: https://github.com/mapswithme/api-android "GitHub Repository" [linkLibProj]: http://developer.android.com/tools/projects/index.html#LibraryProjects "Android Library Project" [linkIntents]: http://developer.android.com/guide/components/intents-filters.html "Intents and Intent Filters" -[linkApiClass]: lib/src/com/mapswithme/maps/api/MapsWithMeApi.java "MapsWithMeApi.java" -[linkPointClass]: lib/src/com/mapswithme/maps/api/MWMPoint.java "MWMPoint.java" -[linkRespClass]: lib/src/com/mapswithme/maps/api/MWMResponse.java "MWMResponse.java" +[linkApiClass]: lib/src/com/mapswithme/maps/api/OrganicMapsApi.java "OrganicMapsApi.java" +[linkPointClass]: lib/src/com/mapswithme/maps/api/OMPoint.java "OMPoint.java" +[linkRespClass]: lib/src/com/mapswithme/maps/api/OMResponse.java "OMResponse.java" [linkSampleSource]: https://github.com/mapswithme/api-android/tree/master/sample-app-capitals "Api Source Code" [linkSampleGooglePlay]: http://play.google.com/store/apps/details?id=com.mapswithme.capitals "Api Demo .apk" [linkTravelGuides]: http://www.guidewithme.com diff --git a/lib/AndroidManifest.xml b/lib/AndroidManifest.xml index 1bea627..5c3706a 100644 --- a/lib/AndroidManifest.xml +++ b/lib/AndroidManifest.xml @@ -1,8 +1,8 @@ - \ No newline at end of file + diff --git a/lib/res/layout/dlg_install_mwm.xml b/lib/res/layout/dlg_install_mwm.xml index 1858369..b547a7e 100644 --- a/lib/res/layout/dlg_install_mwm.xml +++ b/lib/res/layout/dlg_install_mwm.xml @@ -1,6 +1,6 @@