diff options
author | Dmitry Kunin <dkunin@mapswith.me> | 2013-06-12 20:01:07 +0400 |
---|---|---|
committer | Alex Zolotarev <alex@maps.me> | 2015-09-23 01:57:28 +0300 |
commit | 4857533099556abe54cc6a75f2fe7bc2c24aab14 (patch) | |
tree | 7b1766e23fe3819370b18eb0b2111e44d75d03d7 /api | |
parent | 5cae0f8317aecade13fe74646fe66d44525878d2 (diff) |
[android, api] Draft of README.md file.
Diffstat (limited to 'api')
-rw-r--r-- | api/android/README.html | 138 | ||||
-rw-r--r-- | api/android/README.md | 137 |
2 files changed, 275 insertions, 0 deletions
diff --git a/api/android/README.html b/api/android/README.html new file mode 100644 index 0000000000..e339cbbde8 --- /dev/null +++ b/api/android/README.html @@ -0,0 +1,138 @@ +<h1>MapsWithMe Android API: Getting Started</h1> + +<h2>Introduction</h2> + +<p>MapsWithMe Android API (hereinafter referred to as <em>"API Library"</em> or just <em>"library"</em>) +provides interface for client application to perform next tasks:</p> + +<ul> +<li>Show one or set of the points on offline map of <a href="http://mapswith.me/" title="MapsWithMe">MapsWithMe Application</a></li> +<li>Send arbitrary <a href="http://developer.android.com/reference/android/app/PendingIntent.html" title="PendingIntent">PendingIntent</a> with point data when +user asks for more information by pressing "More Info" button in MapsWithMe Application</li> +</ul> + +<p>Thus, you can provide two way communication between your appication and MapsWithMe, +using MapsWithMe to show points of interest (POI) and providing more information in your app.</p> + +<p>Please refer to <a href="http://example.com" title="Sample Application">sample application</a> for demo.</p> + +<h2>Prerequisites</h2> + +<p>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 <a href="http://developer.android.com/guide/components/intents-filters.html" title="Intents and Intent Filters">Intents</a>, <a href="http://developer.android.com/tools/projects/index.html#LibraryProjects" title="Android Library Project">library projects</a>, and <a href="http://developer.android.com/reference/android/app/PendingIntent.html" title="PendingIntent">PendingIntents</a> (recommended) as well. +Your application must target at least <em>android sdk version 7</em>.</p> + +<h2>Integration</h2> + +<p>First step is to clone <a href="http://example.com" title="GitHub Repository">repository</a> or download it as an archive.</p> + +<p>When your are done you find two folders: <em>lib</em> and <em>sample-app-capitals</em>. 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.</p> + +<h2>Classes Overview and HOW TO</h2> + +<p>Core classes you will work with are:</p> + +<ul> +<li><a href="http://example.com" title="MapsWithMeApi.java">com.mapswithme.maps.api.MapsWithMeApi</a> - static class with methods such as <code>showPointOnMap(Activity, double, double, String)</code> etc.</li> +<li><a href="http://example.com" title="MWMPoint.java">com.mapswithme.maps.api.MWMPoint</a> - model of POI, includes lat, lon, name, and id data.</li> +<li><a href="http://example.com" title="MWMResponse.java">com.mapswithme.maps.api.MWMResponse</a> - </li> +</ul> + +<h3>Show Points on the Map</h3> + +<p>The simplest usage:</p> + +<pre><code>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); + } +... + +} +</code></pre> + +<p>For multiple points use <a href="http://example.com" title="MWMPoint.java">MWMPoint</a> class:</p> + +<pre><code>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); +} +</code></pre> + +<h3>Ask MapsWithMe to Call my App</h3> + +<p>We support PendingIntent interaction (just like Android system +NotificationManager does). You need to specify ID for each point to +diftiguish it leter, and PentingIntent that MapsWithMe send back to +your application:</p> + +<pre><code>// Here is how to pass points with ID ant PendingIntent +void showMultiplePointsWithPendingIntent(List<SomeDomainObject> list, PendingIntent pendingIntent) +{ + // Convert objects to MMWPoints + 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); +} + +@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 + handleIntent(intent); +} + +void handleIntent(Intent 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()); +} +</code></pre> + +<h2>Docs [TODO add link to javadoc]</h2> + +<h2>Sample Code [TODO add link to sample code]</h2> + +<h2>FAQ [TODO to be defined]</h2> + +<h2>Support</h2> + +<p>If you have any questions please email to <a href="mailto:api@mapswith.me" title="MapsWithMe Support Contact">api@mapswith.me</a>.</p> diff --git a/api/android/README.md b/api/android/README.md new file mode 100644 index 0000000000..7dd69e34f7 --- /dev/null +++ b/api/android/README.md @@ -0,0 +1,137 @@ +# MapsWithMe Android API: Getting Started + +## Introduction +MapsWithMe Android API (hereinafter referred to as *"API Library"* or just *"library"*) +provides interface for client application to perform next tasks: + +* Show one or set of the points on offline map of [MapsWithMe Application][linkMwm] +* Send arbitrary [PendingIntent][linkPIntent] with point data when + user asks for more information by pressing "More Info" button in MapsWithMe Application + +Thus, you can provide two way communication between your appication and MapsWithMe, +using MapsWithMe to show points of interest (POI) and providing more information in your app. + +Please refer to [sample application][linkSample] 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. +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 7*. +## 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. + +##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, and id data. +* [com.mapswithme.maps.api.MWMResponse][linkRespClass] - + +### 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][linkPointClass] 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 system +NotificationManager does). You need to specify ID for each point to +diftiguish it leter, and PentingIntent that MapsWithMe send back to +your application: + + // Here is how to pass points with ID ant PendingIntent + void showMultiplePointsWithPendingIntent(List<SomeDomainObject> list, PendingIntent pendingIntent) + { + // Convert objects to MMWPoints + 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); + } + + @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 + handleIntent(intent); + } + + void handleIntent(Intent 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()); + } + +## Docs [TODO add link to javadoc] + +## Sample Code [TODO add link to sample code] + +## FAQ [TODO to be defined] + +## Support +If you have any questions please email to [api@mapswith.me][linkSupport]. + +[linkMwm]: http://mapswith.me/ "MapsWithMe" +[linkPIntent]: http://developer.android.com/reference/android/app/PendingIntent.html "PendingIntent" +[linkSample]: http://example.com "Sample Application" +[linkRepo]: http://example.com "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" +[linkSupport]: mailto:api@mapswith.me "MapsWithMe Support Contact" +[linkApiClass]: http://example.com "MapsWithMeApi.java" +[linkPointClass]: http://example.com "MWMPoint.java" +[linkRespClass]: http://example.com "MWMResponse.java" |