From b14e2d8967c757e340f121c2a5c222c6a2106746 Mon Sep 17 00:00:00 2001 From: pogunrek Date: Mon, 18 May 2020 14:40:48 +0200 Subject: [PATCH] ESD-810: Update Product Names Signed-off-by: pogunrek --- CONTRIBUTING.md | 2 +- Documentation/Guides/ContributionGuide.md | 20 ++--- Documentation/Guides/QuickStart.md | 66 +++++++------- Documentation/Guides/UserGuide.md | 88 +++++++++---------- .../Guides_Examples/HelloMSDKUI/README.md | 2 +- .../Guides_Examples/MSDKUIPrimer/README.md | 2 +- MSDKUIDemo/README.md | 4 +- README.md | 16 ++-- 8 files changed, 100 insertions(+), 100 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42a4137d..3f898cbc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to the HERE Mobile SDK UI Kit +# Contributing to the HERE Mobile SDK UI Kit (MSDKUI) Thank you for your interest in contributing to this open source project. Every great project comes with great quality. There are many ways to contribute on this project, whether you want to create an issue, submit bug reports, improve the documentation or add new UI components - we are happy to see your pull requests. diff --git a/Documentation/Guides/ContributionGuide.md b/Documentation/Guides/ContributionGuide.md index 8a75c40f..1428e4c6 100644 --- a/Documentation/Guides/ContributionGuide.md +++ b/Documentation/Guides/ContributionGuide.md @@ -1,4 +1,4 @@ -# MSDKUI Contribution Guide +# HERE Mobile SDK UI Kit (MSDKUI) Contribution Guide This guide is for developers who want to contribute to the MSDKUI codebase, build the MSDKUI library, or run the demo application on their local machines. For using the `MSDKUILib.aar` on your own project, or running the accompanying example apps, please check the [QuickStart](QuickStart.md) guide. @@ -6,7 +6,7 @@ This guide is for developers who want to contribute to the MSDKUI codebase, buil - [Getting the code](#getting-the-code) - [See available Gradle tasks](#see-available-gradle-tasks) -- [Building the HERE UI Kit library](#building-the-here-ui-kit-library) +- [Building the MSDKUI library](#building-the-msdkui-library) - [Building the MSDKUI API Reference from the command line](#building-the-msdkui-api-reference-from-the-command-line) - [Running unit tests for the MSDKUILib](#running-unit-tests-for-the-msdkuilib) - [Generating a unit test coverage report](#generating-a-unit-test-coverage-report) @@ -16,7 +16,7 @@ This guide is for developers who want to contribute to the MSDKUI codebase, buil - [Running unit tests for the MDKUIApp](#running-unit-tests-for-the-mdkuiapp) - [Generating a unit test coverage report](#generating-a-unit-test-coverage-report) - [Running UI tests for the MDKUIApp](#running-ui-tests-for-the-mdkuiapp) - - [Optional: Building the HERE UI Kit Library and the Demo as part of one project](#optional-building-the-here-ui-kit-library-and-the-demo-as-part-of-one-project) + - [Optional: Building the MSDKUI Library and the Demo as part of one project](#optional-building-the-msdkui-library-and-the-demo-as-part-of-one-project) - [Building the Dev app](#building-the-dev-app) - [Commit policy](#commit-policy) - [Writing Git commit messages](#writing-git-commit-messages) @@ -38,11 +38,11 @@ The HERE SDK UI Kit for Android is built using Gradle. For an overview of the av - ./gradlew task from MSDKUIKIT folder to see all lib related tasks - ./gradlew task from MSDKUIDemo folder to see all Demo app related tasks -## Building the HERE UI Kit library +## Building the MSDKUI library -The easiest way to build the HERE Mobile SDK UI Kit library (MSDKUILib) is using the command line: +The easiest way to build the MSDKUI library (MSDKUILib) is using the command line: - Put the `HERE-sdk.aar` file from your HERE SDK package to _MSDKUIKit/libs/_. -- Build the HERE Mobile SDK UI Kit library via Gradle. Navigate to the _MSDKUIKit_ folder and execute: `./gradlew clean :MSDKUILib:assembleRelease`. +- Build the MSDKUI library via Gradle. Navigate to the _MSDKUIKit_ folder and execute: `./gradlew clean :MSDKUILib:assembleRelease`. >**Note:** Please, make sure to set `ANDROID_HOME` to your environment `PATH` variable. It should point to the location where you have installed the Android SDK. @@ -91,9 +91,9 @@ When you register on [developer.here.com](https://developer.here.com), the regis ### Building and Running the Demo -In order to build and to run the demo app with Android Studio, you need to integrate the HERE Mobile SDK (Premium) version 3.15. Additionally, you need to integrate the HERE Mobile SDK UI Kit library. +In order to build and to run the demo app with Android Studio, you need to integrate the HERE Mobile SDK (Premium) version 3.15. Additionally, you need to integrate the MSDKUI library. -- Put the HERE-sdk.aar file from your HERE SDK package and the HERE UI Kit library to _MSDKUIDemo/libs/_. +- Put the HERE-sdk.aar file from your HERE SDK package and the MSDKUI library to _MSDKUIDemo/libs/_. - Open and build the project located at _MSDKUIDemo/_ in Android Studio. - Run it on a device or emulator of your choice. @@ -117,7 +117,7 @@ Switch to command line and navigate to the _MSDKUIDemo_ folder. Execute: `./grad >**Note:** Alternatively, you can also run the UI tests from within Android Studio by right clicking on a specific test or the _androidTest_ subfolder and clicking "Run Tests". You can also directly select the Gradle Task: `MSDKUIApp -> Tasks -> build -> assembleAndroidTest` (right-click and run). -### Optional: Building the HERE UI Kit Library and the Demo as part of one project +### Optional: Building the MSDKUI Library and the Demo as part of one project Usually, it should be sufficient to keep library and Demo project separated. If you are planning to contribute to the Demo app - or to test your new components as part of the Demo app - it may be convenient to build both as part of one Android Studio project. @@ -142,7 +142,7 @@ classpath 'org.jfrog.buildinfo:build-info-extractor-gradle:4.4.15' This project includes a Dev application, which is designed to display MSDKUI views in their raw form. While the Demo app offers a polished experience of the MSDKUI components, it doesn't show all possible states of a view. -1. Put the HERE-sdk.aar file from your HERE Mobile SDK package _and_ the HERE MSDKUI library to `MSDKUIDev/libs/`. Make sure the library is named "MSDKUILib.aar" to match the dependencies in the app's `build.gradle` file. +1. Put the HERE-sdk.aar file from your HERE Mobile SDK package _and_ the MSDKUI library to `MSDKUIDev/libs/`. Make sure the library is named "MSDKUILib.aar" to match the dependencies in the app's `build.gradle` file. 2. Open and build the project located at `MSDKUIDev/` in Android Studio. 3. Run it on a device or an emulator of your choice. diff --git a/Documentation/Guides/QuickStart.md b/Documentation/Guides/QuickStart.md index 60c8a9cf..6cd72803 100644 --- a/Documentation/Guides/QuickStart.md +++ b/Documentation/Guides/QuickStart.md @@ -1,16 +1,16 @@ # Quick Start -Thank you for using the HERE Mobile SDK UI Kit. In this Quick Start guide, we are going to introduce you to the HERE Mobile SDK UI Kit and show you how easy it is to get started. As a very first example, we'll also develop a "Hello HERE Mobile SDK UI Kit" Android application as part of this guide. For more examples and in-depth information on how to work with the HERE Mobile SDK UI Kit framework, please refer to the [User Guide](UserGuide.md). +Thank you for using the HERE Mobile SDK UI Kit (MSDKUI). In this Quick Start guide, we are going to introduce you to the HERE Mobile SDK UI Kit (MSDKUI) and show you how easy it is to get started. As a very first example, we'll also develop a "Hello HERE Mobile SDK UI Kit" Android application as part of this guide. For more examples and in-depth information on how to work with the HERE Mobile SDK UI Kit (MSDKUI) framework, please refer to the [User Guide](UserGuide.md). ## Contents - [How to run the example apps](#how-to-run-the-example-apps) - [How to run the Demo app](#how-to-run-the-demo-app) - [Creating a new Android Project](#creating-a-new-android-project) - - [Integrating the HERE Mobile SDK and the HERE Mobile SDK UI Kit](#integrating-the-here-mobile-sdk-and-the-here-mobile-sdk-ui-kit) + - [Integrating the HERE Mobile SDK and the HERE Mobile SDK UI Kit (MSDKUI)](#integrating-the-here-mobile-sdk-and-the-here-mobile-sdk-ui-kit-msdkui) - [Gradle Setup](#gradle-setup) - [Theme Setup](#theme-setup) - [Setting your HERE Mobile SDK credentials](#setting-your-here-mobile-sdk-credentials) - - [Add your first HERE Mobile SDK UI Kit component](#add-your-first-here-mobile-sdk-ui-kit-component) + - [Add your first HERE Mobile SDK UI Kit (MSDKUI) component](#add-your-first-here-mobile-sdk-ui-kit-msdkui-component) - [Loading the Map](#loading-the-map) @@ -18,7 +18,7 @@ Thank you for using the HERE Mobile SDK UI Kit. In this Quick Start guide, we ar ## How to run the example apps If you just want to try out the accompanying examples, please perform the following steps: -- Include the HERE Mobile SDK 3.15, Premium, and the HERE Mobile SDK UI Kit: Copy the `HERE-sdk.aar` and the `MSDKUILib-release.aar` to the example's _app/libs_ folder (if not done already, [build the MSDKUILib](ContributionGuide.md#building-the-here-ui-kit-library) via Gradle from folder _MSDKUIKit_ and make sure to copy the `HERE-sdk.aar` also to _MSDKUIKit/libs/_. Build the framework by executing: `./gradlew clean :MSDKUILib:assembleRelease`). +- Include the HERE Mobile SDK 3.15, Premium Edition, and the HERE Mobile SDK UI Kit (MSDKUI): Copy the `HERE-sdk.aar` and the `MSDKUILib-release.aar` to the example's _app/libs_ folder (if not done already, [build the MSDKUILib](ContributionGuide.md#building-the-here-ui-kit-library) via Gradle from folder _MSDKUIKit_ and make sure to copy the `HERE-sdk.aar` also to _MSDKUIKit/libs/_. Build the framework by executing: `./gradlew clean :MSDKUILib:assembleRelease`). - Open the project in Android Studio. - Add the credentials for the HERE Mobile SDK to the `AndroidManifest.xml` file: ```xml @@ -37,7 +37,7 @@ When you register on [developer.here.com](https://developer.here.com), the regis For more information on how to set up a new project, please, refer to our guide below which contains much more useful information on how to use the MSDKUI and to build your own apps. -> Please note that the HERE Mobile SDK UI Kit uses [AndroidX](https://developer.android.com/jetpack/androidx). You can migrate an existing project to AndroidX by selecting _Refactor > Migrate to AndroidX_ from the menu bar in Android Studio. +> Please note that the HERE Mobile SDK UI Kit (MSDKUI) uses [AndroidX](https://developer.android.com/jetpack/androidx). You can migrate an existing project to AndroidX by selecting _Refactor > Migrate to AndroidX_ from the menu bar in Android Studio. ## How to run the Demo app Along with the accompanying example apps and code snippets, we also provide a more complex demo app showing a complete and fully functional flow. If you want to try out the Demo application, please take a look at the [Contribution Guide](ContributionGuide.md). @@ -45,38 +45,38 @@ Along with the accompanying example apps and code snippets, we also provide a mo If you want to build your own app, it may be useful to follow the guide below where we will develop step by step a first Hello HERE Mobile SDK UI Kit app in greater detail. ## Creating a new Android Project -Let's start by creating a new Android app. If you want to integrate the HERE Mobile SDK UI Kit into an existing app, you can skip this step. No HERE Mobile SDK or HERE Mobile SDK UI Kit specific code is involved here. +Let's start by creating a new Android app. If you want to integrate the HERE Mobile SDK UI Kit (MSDKUI) into an existing app, you can skip this step. No HERE Mobile SDK or HERE Mobile SDK UI Kit (MSDKUI) specific code is involved here. If you are new to Android development, please follow the guides on [developer.android.com](https://developer.android.com/guide/) to help you get started with the first steps. -For this Quick Start app, we used Android Studio 3.4.2. The minimum supported Android Studio version you can use for development is 3.2 (higher versions are recommended). +For this Quick Start app, we used Android Studio 3.6.3. - Start Android Studio and select _Start a new Android Studio project_. - Select an Application name of your choice, for example _HelloMSDKUI_. - Set a company name. For our example we have used _here.com_. - Set a proper package name. Ideally, make sure that it matches the one used for your HERE credentials. -- This Quick Start guide uses Java, so do not include Kotlin support if you plan to use the same code snippets as provided within this guide. Note that the HERE Mobile SDK UI Kit is fully compatible with Kotlin. See also our HERE Mobile SDK UI Kit demo app which is developed in Kotlin. +- This Quick Start guide uses Java, so do not include Kotlin support if you plan to use the same code snippets as provided within this guide. Note that the HERE Mobile SDK UI Kit (MSDKUI) is fully compatible with Kotlin. See also our HERE Mobile SDK UI Kit (MSDKUI) demo app which is developed in Kotlin. - Select _Phone and Tablet_ - The minimum supported Android API level should be 19 (Android 4.4, KitKat) or higher. - As a final step, select a template of your choice, for example _Empty Activity_ and keep the default name for your main activity on the next screen: _MainActivity_. To ensure backwards compatibility, we recommend using an `AppCompatActivity`. Now let the Gradle sync finish and _run_ the project. Select an emulator or a real device and verify that your project executes as expected. If all goes well, you should see blank view showing a "Hello World"-text. ->**Note:** While all of the functionality of the HERE Mobile SDK UI Kit is accessible from the emulator, usage of a real device is strongly recommended. The overall performance will be better, and some features like gestures are just easier to use on multi-touch-enabled hardware. +>**Note:** While all of the functionality of the HERE Mobile SDK UI Kit (MSDKUI) is accessible from the emulator, usage of a real device is strongly recommended. The overall performance will be better, and some features like gestures are just easier to use on multi-touch-enabled hardware. -### Integrating the HERE Mobile SDK and the HERE Mobile SDK UI Kit -Now that we have a working Android app, we can start integrating the HERE SDK and the HERE Mobile SDK UI Kit library. Make sure you have downloaded the latest HERE Mobile SDK release package including the library AAR artefact usually called `HERE-sdk.aar`. +### Integrating the HERE Mobile SDK and the HERE Mobile SDK UI Kit (MSDKUI) +Now that we have a working Android app, we can start integrating the HERE SDK and the HERE Mobile SDK UI Kit (MSDKUI) library. Make sure you have downloaded the latest HERE Mobile SDK release package including the library AAR artefact usually called `HERE-sdk.aar`. As a next step, we will build the HERE Mobile SDK UI Kit library (MSDKUILib): - Put the `HERE-sdk.aar` file from your HERE SDK package to _MSDKUI-Android/MSDKUIKit/libs/_. -- Build the HERE Mobile SDK UI Kit library via Gradle: Navigate to the _MSDKUIKit_ folder and execute: `./gradlew clean :MSDKUILib:assembleRelease`. +- Build the MSDKUI library via Gradle: Navigate to the _MSDKUIKit_ folder and execute: `./gradlew clean :MSDKUILib:assembleRelease`. >**Note:** Please, make sure to set `ANDROID_HOME` to your environment `PATH` variable. It should point to the location where you have installed the Android SDK. -The built HERE Mobile SDK UI Kit AAR is the located in your new _MSDKUIKit/MSDKUILib/build/outputs/aar/_ subfolder. +The built HERE Mobile SDK UI Kit (MSDKUI) AAR is the located in your new _MSDKUIKit/MSDKUILib/build/outputs/aar/_ subfolder. Now you should have two binaries: `HERE-sdk.aar` and `MSDKUILib-release.aar`. Copy both to the _libs_ folder of your Android project. Usually the path is inside the app folder, for example: `HelloMSDKUI/app/libs`. -More details on integrating the HERE Mobile SDK can be found on [developer.here.com](https://developer.here.com/documentation/android-premium/dev_guide/topics/quick-start.html). For this Quick Start guide, we will integrate the HERE SDK together with the HERE Mobile SDK UI Kit lib. The steps are the same as shown on developer.here.com, except that we integrate the HERE Mobile SDK UI Kit on top. +More details on integrating the HERE Mobile SDK can be found on [developer.here.com](https://developer.here.com/documentation/android-premium/dev_guide/topics/quick-start.html). For this Quick Start guide, we will integrate the HERE SDK together with the MSDKUI lib. The steps are the same as shown on developer.here.com, except that we integrate the HERE Mobile SDK UI Kit (MSDKUI) on top. ### Gradle Setup Within Android Studio, open the _app-level_ `build.gradle` file (to be found under the app folder) and configure the repositories for your project to use a flat hierarchy: @@ -104,9 +104,9 @@ dependencies { Depending on your specific project configuration, you may have other entries here. It is recommended to include always the latest versions. -As you can see, we add both the HERE Mobile SDK _and_ the HERE Mobile SDK UI Kit library as dependencies. Additionally, the HERE Mobile SDK UI Kit requires the latest _AndroidX AppCompat support library_, the _Android Material Design library_ and the supporting _Constraint layout_. The latter two are needed for the layouts of certain HERE Mobile SDK UI Kit components. +As you can see, we add both the HERE Mobile SDK _and_ the MSDKUI library as dependencies. Additionally, the HERE Mobile SDK UI Kit (MSDKUI) requires the latest _AndroidX AppCompat support library_, the _Android Material Design library_ and the supporting _Constraint layout_. The latter two are needed for the layouts of certain HERE Mobile SDK UI Kit components. -Since the HERE Mobile SDK UI Kit uses Lambda expressions, _Java 8_ is required. Open the _app-level_ `build.gradle` file, if not already open. Please, add the following to the Android`-closure to [desugar](https://developer.android.com/studio/write/java8-support) the output of the javac compiler: +Since the HERE Mobile SDK UI Kit (MSDKUI) uses Lambda expressions, _Java 8_ is required. Open the _app-level_ `build.gradle` file, if not already open. Please, add the following to the Android`-closure to [desugar](https://developer.android.com/studio/write/java8-support) the output of the javac compiler: ```java compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 @@ -115,7 +115,7 @@ Since the HERE Mobile SDK UI Kit uses Lambda expressions, _Java 8_ is required. ``` ### Theme Setup -The HERE Mobile SDK UI Kit library offers various options to customize the default look and feel of its containing components. Make sure to derive your own themes from the `MSDKUIDarkTheme`. Other parent themes may be provided in the future. `MSDKUIDarkTheme` itself is derived from `Theme.AppCompat.Light.DarkActionBar`. +The MSDKUI library offers various options to customize the default look and feel of its containing components. Make sure to derive your own themes from the `MSDKUIDarkTheme`. Other parent themes may be provided in the future. `MSDKUIDarkTheme` itself is derived from `Theme.AppCompat.Light.DarkActionBar`. Overwrite the default `styles.xml` (to be found in `res/values`) to set a new base application theme: ```xml @@ -124,10 +124,10 @@ Overwrite the default `styles.xml` (to be found in `res/values`) to set a new ba ``` -Note that this step is required even if you don't plan to use custom themes. The HERE Mobile SDK UI Kit requires `MSDKUIDarkTheme` as parent theme for its components. +Note that this step is required even if you don't plan to use custom themes. The Add your first HERE Mobile SDK UI Kit (MSDKUI) component requires `MSDKUIDarkTheme` as parent theme for its components. ### Setting your HERE Mobile SDK credentials -The HERE Mobile SDK (Premium flavor) must be authenticated by providing a set of credentials specific for your project. If you don't know your credentials, please ask your HERE stakeholder or register on [developer.here.com](https://developer.here.com) and create new ones. +The HERE Mobile SDK (Premium Edition) must be authenticated by providing a set of credentials specific for your project. If you don't know your credentials, please ask your HERE stakeholder or register on [developer.here.com](https://developer.here.com) and create new ones. In order to enter the app id, app code and license key and to provide these to the HERE SDK, please open the `AndroidManifest`-file and edit the following entries. Note that the `meta-data` tags should be nested under the `application`-tag. @@ -147,7 +147,7 @@ Make sure to replace `YOUR_APP_ID`, `YOUR_APP_CODE` and `YOUR_LICENSE_KEY` with >**Note:** If you want to try out our fully functional demo app or one of the [examples](../Guides_Examples), your [registered](https://developer.here.com) bundle identifier must match the [applicationId](https://developer.android.com/studio/build/application-id) in the app's build.gradle. -Since we are using the HERE Mobile SDK UI Kit along with the HERE Mobile SDK, we must make sure to add the required permissions to the manifest. The following permissions are recommended. Please put them nested under the `manifest`-tag: +Since we are using the HERE Mobile SDK UI Kit (MSDKUI) along with the HERE Mobile SDK, we must make sure to add the required permissions to the manifest. The following permissions are recommended. Please put them nested under the `manifest`-tag: ```xml @@ -168,17 +168,17 @@ As the HERE SDK needs to download and store map data, we must establish a map se + android:exported="false" + android:process="global.Here.Map.Service.v3"> - - + ``` -For example, as label use _"ExampleMapService"_ and as intent name you may use: _"com.here.msdkui.example.MapService"_. +For example, as label use _"ExampleMapService"_. ->**Note:** After editing `AndroidManifest.xml`, add a call to `MapSettings.setIsolatedDiskCacheRootPath(String path, String intent)` with the desired cache location and the custom intent name. It is recommended to set the disk cache location under your application directory if you do not want the cache to persist after your app is uninstalled. You can find an example [here](https://developer.here.com/documentation/android-premium/dev_guide/topics/map-service.html) or in the example app's `MapInitializer` helper class. +>**Note:** After editing `AndroidManifest.xml`, add a call to `MapSettings.setIsolatedDiskCacheRootPath(String path)` with the desired cache location. It is recommended to set the disk cache location under your application directory if you do not want the cache to persist after your app is uninstalled. You can find an example [here](https://developer.here.com/documentation/android-premium/dev_guide/topics/map-service.html) or in the example app's `MapInitializer` helper class. Finally make sure to click the _"Sync Project with Gradle Files"_-button. If all goes well, you should see the libraries embedded into your project. Switch to _"Project view"_ and expand the _"External Libraries"_-section. Make sure the following entries are shown: - `HERE-sdk:@aar` @@ -186,8 +186,8 @@ Finally make sure to click the _"Sync Project with Gradle Files"_-button. If all To enable quick Javadoc reference within your Android Studio environment, scroll down to the _External Libraries_ section, right-click on `MSDKUILib:@aar`, and then select _Library Properties_. Click the `+`-button and locate `MSDKUILib-javadoc.jar` (if not done already, [build the MSDKUI API Reference](ContributionGuide.md#building-the-msdkui-api-reference-from-the-command-line) via Gradle: `./gradlew clean :MSDKUILib:javadocJar`). -### Add your first HERE Mobile SDK UI Kit component -If you succeed with the above steps, we have the HERE Mobile SDK UI Kit library and the HERE Mobile SDK ready for use. Our app consists only of a single activity, accompanied by a layout file usually called `activity_main.xml` - if you kept the default `MainActivity` class name. +### Add your first HERE Mobile SDK UI Kit (MSDKUI) component +If you succeed with the above steps, we have the MSDKUI library and the HERE Mobile SDK ready for use. Our app consists only of a single activity, accompanied by a layout file usually called `activity_main.xml` - if you kept the default `MainActivity` class name. If you started with an empty Android project, the default layout was hosting a "Hello World"-`TextView`. Replace the entire content of the existing `activity_main` layout file with the following vertical `LinearLayout`: ```xml @@ -210,21 +210,21 @@ If you started with an empty Android project, the default layout was hosting a " android:layout_weight="1"/> ``` -Our first HERE Mobile SDK UI Kit component for this example is `WaypointList` component. A `WaypointList` contains items describing waypoints for which a route can be calculated. Since `WaypointList` is a direct child of `RecyclerView`, it behaves like you would expect from any other `RecyclerView`. +Our first HERE Mobile SDK UI Kit (MSDKUI) component for this example is `WaypointList` component. A `WaypointList` contains items describing waypoints for which a route can be calculated. Since `WaypointList` is a direct child of `RecyclerView`, it behaves like you would expect from any other `RecyclerView`. Below the `WaypointList` we show the HERE `AndroidXMapFragment`. Note that the map will occupy as much space as allowed by the `WaypointList`, since we are giving it a layout weight of 1. ### Loading the Map Before we can start using the `WaypointList` component, we have to prepare loading the `AndroidXMapFragment`. As described on [developer.here.com](https://developer.here.com/documentation/android-premium/dev_guide/topics/app-create-simple.html), we have to request the required [Android permissions](https://developer.here.com/documentation/android-premium/topics/request-android-permissions.html) first. Then we can initialize the `AndroidXMapFragment`. -As our focus for this Quick Start guide is on using the HERE Mobile SDK UI Kit components, we have wrapped both steps in a helper class called `MapInitializer`. For implementation details, please check the example's code. You can use your own wrapper class or follow the steps on [developer.here.com](https://developer.here.com/documentation/android-premium/dev_guide/topics/app-create-simple.html). +As our focus for this Quick Start guide is on using the HERE Mobile SDK UI Kit (MSDKUI) components, we have wrapped both steps in a helper class called `MapInitializer`. For implementation details, please check the example's code. You can use your own wrapper class or follow the steps on [developer.here.com](https://developer.here.com/documentation/android-premium/dev_guide/topics/app-create-simple.html). -Once the HERE `AndroidXMapFragment` is successfully loaded, we want to show a `Toast` message with the current version of the HERE Mobile SDK UI Kit library: +Once the HERE `AndroidXMapFragment` is successfully loaded, we want to show a `Toast` message with the current version of the MSDKUI library: ```java Toast.makeText(this, "HERE MSDK UI Kit version: " + com.here.msdkui.BuildConfig.VERSION_NAME, Toast.LENGTH_SHORT).show(); ``` -Now it's time to populate our first HERE Mobile SDK UI Kit component. For this Quick Start example, we just want to verify that we can access and use a HERE Mobile SDK UI Kit component. The `WaypointList` by default holds two empty waypoints. You can add more waypoints, remove waypoints or modify existing waypoints. A `WaypointList` can hold an unlimited number of stopovers, where the first waypoint marks the start of the route, while the last waypoint marks the destination of the route. For the sake of this Quick Start guide, we want to show the traditional "Hello World"-message by setting custom names for the waypoints. +Now it's time to populate our first HERE Mobile SDK UI Kit (MSDKUI) component. For this Quick Start example, we just want to verify that we can access and use a HERE Mobile SDK UI Kit (MSDKUI) component. The `WaypointList` by default holds two empty waypoints. You can add more waypoints, remove waypoints or modify existing waypoints. A `WaypointList` can hold an unlimited number of stopovers, where the first waypoint marks the start of the route, while the last waypoint marks the destination of the route. For the sake of this Quick Start guide, we want to show the traditional "Hello World"-message by setting custom names for the waypoints. ```java List waypointEntries = new ArrayList<>(); @@ -241,7 +241,7 @@ waypointList.setEntries(waypointEntries); The order in the array defines the order of how the waypoints shall appear in the `WaypointList`. However, the component also allows to interactively shuffle the waypoints around, using the right-hand drag handles - or do delete waypoints by tapping the _minus_ buttons on the left side. -The HERE Mobile SDK UI Kit uses the `WaypointEntry` class as a wrapper to hold coordinates that can be used for route calculation. By default, the component will show raw coordinate values, but you can also set custom names for each waypoint - for example street names. Here we use an overloaded constructor to directly pass in a `String` representation for each waypoint to split the "Hello HERE Mobile SDK UI Kit!"-message upon two waypoint entries. +The HERE Mobile SDK UI Kit (MSDKUI) uses the `WaypointEntry` class as a wrapper to hold coordinates that can be used for route calculation. By default, the component will show raw coordinate values, but you can also set custom names for each waypoint - for example street names. Here we use an overloaded constructor to directly pass in a `String` representation for each waypoint to split the "Hello HERE Mobile SDK UI Kit!"-message upon two waypoint entries. By calling the `findViewById()`-method of our `Activity`, we lookup the inflated instance of our `WaypointList` and finally set the entries we want to show. @@ -251,4 +251,4 @@ Now it's time to build and run the app. If all goes well, you should see a `Wayp

-Congratulations, you have successfully mastered your first steps in using the HERE Mobile SDK UI Kit for Android. If you want to see more examples and code snippets, please have a look at our [User Guide](UserGuide.md). Thank you! +Congratulations, you have successfully mastered your first steps in using the HERE Mobile SDK UI Kit (MSDKUI) for Android. If you want to see more examples and code snippets, please have a look at our [User Guide](UserGuide.md). Thank you! diff --git a/Documentation/Guides/UserGuide.md b/Documentation/Guides/UserGuide.md index 98ab61f8..c7a219ed 100755 --- a/Documentation/Guides/UserGuide.md +++ b/Documentation/Guides/UserGuide.md @@ -1,16 +1,16 @@ -# HERE Mobile SDK UI Kit - User Guide -Are you looking for a framework that lets you build feature-rich and compelling user interfaces on top of the HERE Mobile SDK, _Premium_ edition? Then the HERE Mobile SDK UI Kit for iOS and Android is the perfect companion for you. +# HERE Mobile SDK UI Kit (MSDKUI) - User Guide +Are you looking for a framework that lets you build feature-rich and compelling user interfaces on top of the HERE Mobile SDK, _Premium_ Edition? Then the HERE Mobile SDK UI Kit (MSDKUI) for iOS and Android is the perfect companion for you. -This user guide describes the general workflow using the HERE Mobile SDK UI Kit and its components in detail. If you are looking for a quick overview, please look at our [README](../../README.md), our [Quick Start](QuickStart.md) guide or the latest _Release Notes_. +This user guide describes the general workflow using the HERE Mobile SDK UI Kit (MSDKUI) and its components in detail. If you are looking for a quick overview, please look at our [README](../../README.md), our [Quick Start](QuickStart.md) guide or the latest _Release Notes_. ## Contents -- [Why use the HERE Mobile SDK UI Kit?](#why-use-the-here-mobile-sdk-ui-kit) +- [Why use the HERE Mobile SDK UI Kit (MSDKUI)?](#why-use-the-here-mobile-sdk-ui-kit-msdkui) - [Where to start?](#where-to-start) - [How to read this guide?](#how-to-read-this-guide) -- [Getting started - A HERE Mobile SDK UI Kit Primer](#getting-started---a-here-mobile-sdk-ui-kit-primer) -- [Overview of the HERE Mobile SDK UI Kit Primer example](#overview-of-the-here-mobile-sdk-ui-kit-primer-example) -- [Adding HERE Mobile SDK UI Kit components](#adding-here-mobile-sdk-ui-kit-components) +- [Getting started - A HERE Mobile SDK UI Kit (MSDKUI) Primer](#getting-started---a-here-mobile-sdk-ui-kit-msdkui-primer) +- [Overview of the HERE Mobile SDK UI Kit (MSDKUI) Primer example](#overview-of-the-here-mobile-sdk-ui-kit-msdkui-primer-example) +- [Adding HERE Mobile SDK UI Kit (MSDKUI) components](#adding-here-mobile-sdk-ui-kit-msdkui-components) - [Loading the map view](#loading-the-map-view) - [Using the WaypointList](#using-the-waypointlist) - [Calculating the route](#calculating-the-route) @@ -23,45 +23,45 @@ This user guide describes the general workflow using the HERE Mobile SDK UI Kit -## Why use the HERE Mobile SDK UI Kit? -The HERE Mobile SDK UI Kit provides highly flexible and customizable User Interface building blocks that can be freely combined and arranged with your own UI components - with just a few lines of code. +## Why use the HERE Mobile SDK UI Kit (MSDKUI)? +The HERE Mobile SDK UI Kit (MSDKUI) provides highly flexible and customizable User Interface building blocks that can be freely combined and arranged with your own UI components - with just a few lines of code. -The HERE Mobile SDK UI Kit builds upon optimized native platform code to fully support Xcode's _Interface Builder_ and Android Studio's _Layout Editor_ resulting in reduced development time and a faster time to market for your apps. +The HERE Mobile SDK UI Kit (MSDKUI) builds upon optimized native platform code to fully support Xcode's _Interface Builder_ and Android Studio's _Layout Editor_ resulting in reduced development time and a faster time to market for your apps. - **Cleaner code:** By using the HERE Mobile SDK UI Kit's already assembled modular high- and low-level components, you can easily decouple existing (or new) HERE Mobile SDK logic from your UI modules and other parts of your application. - **Easy to learn:** Each prebuilt component allows for straight-forward customization, either by switching on/off a predefined set of styles or by customizing the views programmatically. As each component is based on platform code, it behaves exactly like you would expect from any other native UI component you may have already in use. -- **Flexible:** All HERE Mobile SDK UI Kit components can be independently integrated from each other - allowing extensible cutting-edge user interfaces. Imagine an interactive route summary mixed with customized planning options directly showing the route to your facility? Or presenting route maneuvers based on the user's traffic preference on the same view? No matter what kind of user flow you want to create, with the HERE Mobile SDK UI Kit it is now all in your hands - making the HERE Mobile SDK a more powerful development tool than ever before. +- **Flexible:** All HERE Mobile SDK UI Kit (MSDKUI) components can be independently integrated from each other - allowing extensible cutting-edge user interfaces. Imagine an interactive route summary mixed with customized planning options directly showing the route to your facility? Or presenting route maneuvers based on the user's traffic preference on the same view? No matter what kind of user flow you want to create, with the HERE Mobile SDK UI Kit (MSDKUI) it is now all in your hands - making the HERE Mobile SDK a more powerful development tool than ever before. -With the HERE Mobile SDK UI Kit, realizing complete apps including comprehensive route planning and state-of-the-art guidance becomes a matter of minutes. While hiding the underlying complexity, you still have all the freedom you need to build unique and powerful apps - take a quick tour with our [HERE Mobile SDK UI Kit Primer](#getting-started---a-here-mobile-sdk-ui-kit-primer) to see a practical example. +With the HERE Mobile SDK UI Kit (MSDKUI), realizing complete apps including comprehensive route planning and state-of-the-art guidance becomes a matter of minutes. While hiding the underlying complexity, you still have all the freedom you need to build unique and powerful apps - take a quick tour with our [HERE Mobile SDK UI Kit (MSDKUI) Primer](#getting-started---a-here-mobile-sdk-ui-kit-msdkui-primer) to see a practical example. -Version 2.x of the HERE Mobile SDK UI Kit mainly focuses on enabling user experiences related to route planning and guidance. The HERE Mobile SDK UI Kit components are available for iOS and Android, supporting Java and Kotlin on Android, likewise Swift on iOS. +Version 2.x of the HERE Mobile SDK UI Kit (MSDKUI) mainly focuses on enabling user experiences related to route planning and guidance. The HERE Mobile SDK UI Kit (MSDKUI) components are available for iOS and Android, supporting Java and Kotlin on Android, likewise Swift on iOS. ## Where to start? -- If you haven't done so, please read our [Quick Start](QuickStart.md) guide to see how you can integrate the HERE Mobile SDK UI Kit into your own apps. +- If you haven't done so, please read our [Quick Start](QuickStart.md) guide to see how you can integrate the HERE Mobile SDK UI Kit (MSDKUI) into your own apps. - Check the [API Reference](https://heremaps.github.io/msdkui-android/) that can also be built locally using the command line, see [Contribution Guide](ContributionGuide.md). - You can also find: - Numerous [examples](../Guides_Examples/) accompanying this user guide - A HERE MSDK UI [demo app](../../MSDKUIDemo/) showcasing most features of the HERE Mobile SDK UI Kit in production-ready quality -- Read the [HERE Mobile SDK UI Kit Primer](#getting-started---a-here-mobile-sdk-ui-kit-primer) chapter of this user guide. +- Read the [HERE Mobile SDK UI Kit (MSDKUI) Primer](#getting-started---a-here-mobile-sdk-ui-kit-msdkui-primer) chapter of this user guide. ## How to read this guide? -In the following sections we will guide you through the most common usage scenarios and reveal tips and easy-to-understand guidelines to help you get the most out of using the HERE Mobile SDK UI Kit for Android. All _main_ sections can be read independent from each other, so you can skip any section and dive straight into the topics you are most interested in. +In the following sections we will guide you through the most common usage scenarios and reveal tips and easy-to-understand guidelines to help you get the most out of using the HERE Mobile SDK UI Kit (MSDKUI) for Android. All _main_ sections can be read independent from each other, so you can skip any section and dive straight into the topics you are most interested in. ->**Note:** All examples that are built as part of this user guide are optimized for portrait mode to keep the projects light weighted and focused. The HERE Mobile SDK UI Kit fully supports portrait _and_ landscape mode. Adapting user interfaces for specific resolutions and orientations depends on your specific requirements - and taste - which is beyond the scope of this document. If supporting landscape requires specific attention or differs from standard Android behavior, it is noted down - otherwise not. +>**Note:** All examples that are built as part of this user guide are optimized for portrait mode to keep the projects light weighted and focused. The HERE Mobile SDK UI Kit (MSDKUI) fully supports portrait _and_ landscape mode. Adapting user interfaces for specific resolutions and orientations depends on your specific requirements - and taste - which is beyond the scope of this document. If supporting landscape requires specific attention or differs from standard Android behavior, it is noted down - otherwise not. -All HERE Mobile SDK UI Kit components support initialization from layouts or by code (programmatically). For most examples, we recommend using layouts. As you can use HERE Mobile SDK UI Kit components like any other view or 3rd party custom component, the general workflow does not contain any specific treatment. If you are new to working with views and layouts under Android, we recommend to read Android's [Layout Guide](https://developer.android.com/guide/topics/ui/declaring-layout). +All HERE Mobile SDK UI Kit (MSDKUI) components support initialization from layouts or by code (programmatically). For most examples, we recommend using layouts. As you can use HERE Mobile SDK UI Kit (MSDKUI) components like any other view or 3rd party custom component, the general workflow does not contain any specific treatment. If you are new to working with views and layouts under Android, we recommend to read Android's [Layout Guide](https://developer.android.com/guide/topics/ui/declaring-layout). -## Getting started - A HERE Mobile SDK UI Kit Primer -In this short tutorial, we are guiding you through your first application with the HERE Mobile SDK UI Kit. We are creating a small route planning application and provide reusable code snippets and guidelines on how to avoid the most common pitfalls. The resulting app is kept as simple as possible - feel free to modify or extend it based on your own taste and needs. +## Getting started - A HERE Mobile SDK UI Kit (MSDKUI) Primer +In this short tutorial, we are guiding you through your first application with the HERE Mobile SDK UI Kit (MSDKUI). We are creating a small route planning application and provide reusable code snippets and guidelines on how to avoid the most common pitfalls. The resulting app is kept as simple as possible - feel free to modify or extend it based on your own taste and needs. ->**Note:** For integrating the HERE Mobile SDK UI Kit framework, please have a look at our [Quick Start](QuickStart.md) to safely guide you through the first steps. +>**Note:** For integrating the HERE Mobile SDK UI Kit (MSDKUI) framework, please have a look at our [Quick Start](QuickStart.md) to safely guide you through the first steps. You can find the complete example code of the _MSDKUIPrimer_ app in the [examples section](../Guides_Examples/). We recommend that you follow this tutorial step-by-step. However, if you get stuck or if you just want to inspect the resulting code of this tutorial, please refer to the app as a point of reference. -## Overview of the HERE Mobile SDK UI Kit Primer example -The HERE Mobile SDK UI Kit Primer example app consists of three screens illustrating some of the main HERE Mobile SDK UI Kit components _in action_: +## Overview of the HERE Mobile SDK UI Kit (MSDKUI) Primer example +The HERE Mobile SDK UI Kit (MSDKUI) Primer example app consists of three screens illustrating some of the main HERE Mobile SDK UI Kit (MSDKUI) components _in action_: **Main Screen** (`MainActivity.java`) - Shows a programmatically pre-populated `WaypointList` @@ -79,10 +79,10 @@ The HERE Mobile SDK UI Kit Primer example app consists of three screens illustra - An `AndroidXMapFragment` to show the current position and orientation on the map - An Android `Button` to stop guidance -First we need to create a new Android project, integrate the HERE Mobile SDK and the HERE Mobile SDK UI Kit. If you followed the [Quick Start](QuickStart.md) guide, you have already created a `MainActivity` as the main entry point to your application. If you prefer, you can also integrate this example into an existing application. The following steps will remain the same. +First we need to create a new Android project, integrate the HERE Mobile SDK and the HERE Mobile SDK UI Kit (MSDKUI). If you followed the [Quick Start](QuickStart.md) guide, you have already created a `MainActivity` as the main entry point to your application. If you prefer, you can also integrate this example into an existing application. The following steps will remain the same. -## Adding HERE Mobile SDK UI Kit components -Let's add the first HERE Mobile SDK UI Kit components to our new project. As outlined before, we want to show two HERE Mobile SDK UI Kit components on our `MainActivity`: +## Adding HERE Mobile SDK UI Kit (MSDKUI) components +Let's add the first HERE Mobile SDK UI Kit (MSDKUI) components to our new project. As outlined before, we want to show two HERE Mobile SDK UI Kit (MSDKUI) components on our `MainActivity`: - `WaypointList` - `TransportModePanel` @@ -120,23 +120,23 @@ For this example, we use a `LinearLayout` as parent layout to group our componen ``` For this layout we have nested four components ordered from top to bottom: -- A HERE Mobile SDK UI Kit component: `WaypointList` -- A HERE Mobile SDK UI Kit component: `TransportModePanel` +- A HERE Mobile SDK UI Kit (MSDKUI) component: `WaypointList` +- A HERE Mobile SDK UI Kit (MSDKUI) component: `TransportModePanel` - An `AndroidXMapFragment` to show a route - A `Button` to advance to the next activity Note that all components share the same namespace `com.here.msdkui.`. In this case, both components belong to the `routing` module. -Since all HERE Mobile SDK UI Kit components are direct or indirect children of `View`, they behave like any other `View` component. +Since all HERE Mobile SDK UI Kit (MSDKUI) components are direct or indirect children of `View`, they behave like any other `View` component. ### Loading the map view -Before we can start using our HERE Mobile SDK UI Kit components, please make sure to initialize the HERE `AndroidXMapFragment` as shown in our [Quick Start](QuickStart.md) guide. We use a wrapper class called `MapInitializer` to request the required Android permissions and load the `AndroidXMapFragment`: +Before we can start using our HERE Mobile SDK UI Kit (MSDKUI) components, please make sure to initialize the HERE `AndroidXMapFragment` as shown in our [Quick Start](QuickStart.md) guide. We use a wrapper class called `MapInitializer` to request the required Android permissions and load the `AndroidXMapFragment`: ```java mapInitializer = new MapInitializer(this, this::onMapLoaded); ``` -Alternatively, you can use your own wrapper class or follow the steps on [developer.here.com](https://developer.here.com/documentation/android-premium/dev_guide/topics/app-create-simple.html). Please find the implementation details of how to initialize a HERE `AndroidXMapFragment` in the source code of the example - or look for other HERE SDK examples on [GitHub](https://github.com/heremaps/here-android-sdk-examples). This step does not involve any HERE Mobile SDK UI Kit specific actions. +Alternatively, you can use your own wrapper class or follow the steps on [developer.here.com](https://developer.here.com/documentation/android-premium/dev_guide/topics/app-create-simple.html). Please find the implementation details of how to initialize a HERE `AndroidXMapFragment` in the source code of the example - or look for other HERE SDK examples on [GitHub](https://github.com/heremaps/here-android-sdk-examples). This step does not involve any HERE Mobile SDK UI Kit (MSDKUI) specific actions. -Usually, loading the map can take place in your Activity's `onCreate()`-method. Once the map is successfully loaded, we can access our inflated HERE Mobile SDK UI Kit components: +Usually, loading the map can take place in your Activity's `onCreate()`-method. Once the map is successfully loaded, we can access our inflated HERE Mobile SDK UI Kit (MSDKUI) components: ```java private WaypointList waypointList; private TransportModePanel transportModePanel; @@ -152,7 +152,7 @@ private void onMapLoaded(Map hereMap) { ## Using the WaypointList Now we have references to our components at hand, so we can start using them and attach the behavior we desire. For this Primer tutorial, we want to add a few waypoints programmatically. -HERE Mobile SDK UI Kit provides the `WaypointEntry` class as a wrapper to allow modification of certain attributes, so that you can set - for example - street names for each waypoint instead of showing the raw coordinates (default). Please see the [Quick Start](QuickStart.md) guide for an example. +HERE Mobile SDK UI Kit (MSDKUI) provides the `WaypointEntry` class as a wrapper to allow modification of certain attributes, so that you can set - for example - street names for each waypoint instead of showing the raw coordinates (default). Please see the [Quick Start](QuickStart.md) guide for an example. ```java List waypointEntries = new ArrayList<>(); waypointEntries.add(new WaypointEntry(new RouteWaypoint(new GeoCoordinate(52.53852,13.42506)))); @@ -166,7 +166,7 @@ As a next step, we need to add the `WaypointEntry` objects to the `WaypointList` waypointList.setEntries(waypointEntries); ``` -Note that order matters, but don't worry, the `WaypointList` HERE Mobile SDK UI Kit component by default already provides drag handles to change the order afterwards. +Note that order matters, but don't worry, the `WaypointList` HERE Mobile SDK UI Kit (MSDKUI) component by default already provides drag handles to change the order afterwards. However, we also want to get notified, whenever the user did any interaction with the `WaypointList`. Therefore we can attach a listener to the `WaypointList`. It provides the following callbacks: @@ -232,7 +232,7 @@ TransportMode transportMode = transportModePanel.getSelectedTransportMode(); Note that we show a route on the map once route calculation is completed. In this example, we show only the first calculated route - even if more routes could be found. ## Using the TransportModePanel -As mentioned in the previous section, we want to calculate a route for a specific transportation mode. Therefore we have added the `TransportModePanel` HERE Mobile SDK UI Kit component. By default it shows all supported transportation modes: +As mentioned in the previous section, we want to calculate a route for a specific transportation mode. Therefore we have added the `TransportModePanel` HERE Mobile SDK UI Kit (MSDKUI) component. By default it shows all supported transportation modes: - `RouteOptions.TransportMode.CAR` - `RouteOptions.TransportMode.TRUCK` - `RouteOptions.TransportMode.PEDESTRIAN` @@ -297,7 +297,7 @@ The screenshot shows how the updated `MainActivity` could look like:

## Implementing the route details screen -In the previous screen the user was able to calculate a route based on her or his waypoint selection and a suitable route mode. Now we want to show a summary for the found routes and their maneuvers on a new screen. As described above, we will show this in the `RouteDetailsActivity` of our HERE Mobile SDK UI Kit Primer example app. The `RouteDetailsActivity` controller holds two HERE Mobile SDK UI Kit components: +In the previous screen the user was able to calculate a route based on her or his waypoint selection and a suitable route mode. Now we want to show a summary for the found routes and their maneuvers on a new screen. As described above, we will show this in the `RouteDetailsActivity` of our HERE Mobile SDK UI Kit (MSDKUI) Primer example app. The `RouteDetailsActivity` controller holds two HERE Mobile SDK UI Kit (MSDKUI) components: - `RouteDescriptionList`: Shows all found routes as a summary in a scrollable list - `ManeuverList`: Shows all maneuvers belonging to a route @@ -331,7 +331,7 @@ First, we need to set up our layout: For this example we show both components on one screen, giving the `ManeuverList` 2/3 of the available space, since the `RouteDecriptionList` is expected to show only up to five routes. -You may look at our demo app for an alternative user interface approach. Note that the HERE Mobile SDK UI Kit does not promote any specific flow how it's component must be arranged - it all depends on your specific needs and taste. +You may look at our demo app for an alternative user interface approach. Note that the HERE Mobile SDK UI Kit (MSDKUI) does not promote any specific flow how it's component must be arranged - it all depends on your specific needs and taste. Again, we retrieve our components from layout in the Activity's `onCreate()`-method: ```java @@ -354,7 +354,7 @@ routeDescriptionList.setRoutesResult(RouteCalculator.getInstance().lastCalculate Note that we use a `RouteCalculator` convenience class to access the last calculated routes. If you are interested in the implementation details, please have a look at the example code. -Since we want to get notified once a user selects a route, we can set a `CustomRecyclerView.OnItemClickedListener`. The `RouteDescriptionList` is a child of a `CustomRecyclerView` which derives from `RecyclerView`. To simplify usage, the HERE Mobile SDK UI Kit provides a `CustomRecyclerView` which allows click handling on list items: +Since we want to get notified once a user selects a route, we can set a `CustomRecyclerView.OnItemClickedListener`. The `RouteDescriptionList` is a child of a `CustomRecyclerView` which derives from `RecyclerView`. To simplify usage, the HERE Mobile SDK UI Kit (MSDKUI) provides a `CustomRecyclerView` which allows click handling on list items: ```java routeDescriptionList.setOnItemClickedListener(new CustomRecyclerView.OnItemClickedListener() { @Override @@ -384,7 +384,7 @@ maneuverList.setRoute(selectedRoute);

-Like for all HERE Mobile SDK UI Kit's list components, we can get notified once a user selects a specific maneuver by tapping on it. In order to react on this event we set the `CustomRecyclerView.OnItemClickedListener()` to know when an item of the list was clicked: +Like for all HERE Mobile SDK UI Kit's (MSDKUI) list components, we can get notified once a user selects a specific maneuver by tapping on it. In order to react on this event we set the `CustomRecyclerView.OnItemClickedListener()` to know when an item of the list was clicked: ```java maneuverList.setOnItemClickedListener(new CustomRecyclerView.OnItemClickedListener() { @Override @@ -400,7 +400,7 @@ maneuverList.setOnItemClickedListener(new CustomRecyclerView.OnItemClickedListen ``` ## Implementing the guidance screen -To finish our quick overview, we want to use the selected route from the previous step to start guidance along that route. For this, we only need one new HERE Mobile SDK UI Kit component: +To finish our quick overview, we want to use the selected route from the previous step to start guidance along that route. For this, we only need one new HERE Mobile SDK UI Kit (MSDKUI) component: - `GuidanceManeuverView` Since the contents of the `GuidanceManeuverView` may vary in height, it is recommended to _not_ set a fixed layout height. Note that all guidance components wrap their content without an additional padding. This allows us to specify the desired value in our layout. @@ -435,7 +435,7 @@ In addition, we also want to show a map during guidance to let the user orientat ``` ## Using the GuidanceManeuverView -The `GuidanceManeuverView` is a panel where information about the next maneuvers will appear. As with all HERE Mobile SDK UI Kit components, it is already configured, so you only need to pass in the desired state based on the provided `GuidanceManeuverData`. +The `GuidanceManeuverView` is a panel where information about the next maneuvers will appear. As with all HERE Mobile SDK UI Kit (MSDKUI) components, it is already configured, so you only need to pass in the desired state based on the provided `GuidanceManeuverData`. This data is provided by the `GuidanceManeuverPresenter` helper class, that accepts a `GuidanceManeuverListener` to notify the listener once new `GuidanceManeuverData` is available: ```java @@ -492,9 +492,9 @@ Once we resume the `GuidanceManeuverPresenter`, we may also want to start guidan More information on how to start guidance using the HERE Mobile SDK is described on [developer.here.com](https://developer.here.com/documentation/android-premium/topics/map-guidance.html). ## Where to go from here? -Congratulations, by following this HERE Mobile SDK UI Kit Primer tutorial, you have discovered the basic HERE Mobile SDK UI Kit components and how they can work together to build extremely powerful apps. Please take a look at the [API Reference](https://heremaps.github.io/msdkui-android/) to learn more about the various HERE Mobile SDK UI Kit components. +Congratulations, by following this HERE Mobile SDK UI Kit (MSDKUI) Primer tutorial, you have discovered the basic HERE Mobile SDK UI Kit (MSDKUI) components and how they can work together to build extremely powerful apps. Please take a look at the [API Reference](https://heremaps.github.io/msdkui-android/) to learn more about the various HERE Mobile SDK UI Kit (MSDKUI) components. -There you can also find more example code, and our demo application that shows most of the available HERE Mobile SDK UI Kit components and capabilities. +There you can also find more example code, and our demo application that shows most of the available HERE Mobile SDK UI Kit (MSDKUI) components and capabilities. |![](Images/demo1.png) | ![](Images/demo2.png) | ![](Images/demo3.png) | |:---:|:---:|:---:| @@ -502,4 +502,4 @@ There you can also find more example code, and our demo application that shows m The screenshots above show the "MSDK UI Demo" app. -We are happy to hear your feedback. Please [contact us](https://developer.here.com/contact-us) for any questions, suggestions or improvements. Thank you for using the HERE Mobile SDK UI Kit. +We are happy to hear your feedback. Please [contact us](https://developer.here.com/contact-us) for any questions, suggestions or improvements. Thank you for using the HERE Mobile SDK UI Kit (MSDKUI). diff --git a/Documentation/Guides_Examples/HelloMSDKUI/README.md b/Documentation/Guides_Examples/HelloMSDKUI/README.md index abcea8e7..19a733e3 100644 --- a/Documentation/Guides_Examples/HelloMSDKUI/README.md +++ b/Documentation/Guides_Examples/HelloMSDKUI/README.md @@ -1,4 +1,4 @@ -This app shows how to integrate the HERE Mobile SDK and the HERE Mobile SDK UI Kit framework. If everything is set up correctly, a simple component will show the traditional "Hello World"-message. +This app shows how to integrate the HERE Mobile SDK and the HERE Mobile SDK UI Kit (MSDKUI) framework. If everything is set up correctly, a simple component will show the traditional "Hello World"-message. Please see the [QuickStart](../../Guides/QuickStart.md) guide for instructions on how to build and to run this example app. diff --git a/Documentation/Guides_Examples/MSDKUIPrimer/README.md b/Documentation/Guides_Examples/MSDKUIPrimer/README.md index 40de2857..14a2bf21 100644 --- a/Documentation/Guides_Examples/MSDKUIPrimer/README.md +++ b/Documentation/Guides_Examples/MSDKUIPrimer/README.md @@ -1,4 +1,4 @@ -This app shows how several HERE Mobile SDK UI Kit components can work together to provide a simple user flow from route planning to guidance. It also shows how to present route details and a maneuver list. +This app shows how several HERE Mobile SDK UI Kit (MSDKUI) components can work together to provide a simple user flow from route planning to guidance. It also shows how to present route details and a maneuver list. Please see the [QuickStart](../../Guides/QuickStart.md) guide for instructions on how to build and to run this example app. diff --git a/MSDKUIDemo/README.md b/MSDKUIDemo/README.md index 7dcf7856..89baf473 100644 --- a/MSDKUIDemo/README.md +++ b/MSDKUIDemo/README.md @@ -1,5 +1,5 @@ -This demo app shows a complete and fully functional flow using the HERE Mobile SDK and the HERE UI Kit. +This demo app shows a complete and fully functional flow using the HERE Mobile SDK and the HERE Mobile SDK UI Kit (MSDKUI). Please see the [QuickStart](../../../Guides/QuickStart.md) guide for instructions on how to build and run this app. -The inner workings of the HERE Mobile SDK UI Kit framework are explained in detail in our [User Guide](../../../Guides/UserGuide.md). +The inner workings of the HERE Mobile SDK UI Kit (MSDKUI) framework are explained in detail in our [User Guide](../../../Guides/UserGuide.md). diff --git a/README.md b/README.md index c67c7152..238a3d22 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# What is the HERE Mobile SDK UI Kit? -The HERE Mobile SDK UI Kit is a framework that provides modular and highly customizable user interface components that can be used on top of the HERE Mobile SDKs for iOS and Android ([Premium edition](https://developer.here.com/develop/mobile-sdks)). +# What is the HERE Mobile SDK UI Kit (MSDKUI)? +The HERE Mobile SDK UI Kit (MSDKUI) is a framework that provides modular and highly customizable user interface components that can be used on top of the HERE Mobile SDKs for iOS and Android ([Premium Edition](https://developer.here.com/develop/mobile-sdks)). ![](Documentation/Guides/Images/UIKit_Intro.png) -Rapidly build beautiful UIs for common use cases and scenarios within minutes. Version 2.x of the HERE Mobile SDK UI Kit will mainly focus on route planning, maneuver details and guidance. More components will follow subsequently with the next releases. +Rapidly build beautiful UIs for common use cases and scenarios within minutes. Version 2.x of the HERE Mobile SDK UI Kit (MSDKUI) will mainly focus on route planning, maneuver details and guidance. More components will follow subsequently with the next releases. ## Feature List - Modular UI building blocks @@ -12,10 +12,10 @@ Rapidly build beautiful UIs for common use cases and scenarios within minutes. V - Full support for all device orientations and screen sizes - Already localized for 14+ languages - Full accessibility support including voice over for customers with special needs -- Designed for the HERE Mobile SDK (iOS and Android, Premium edition) +- Designed for the HERE Mobile SDKs for iOS and Android ([Premium Edition](https://developer.here.com/develop/mobile-sdks)). ## Component Overview -The HERE Mobile SDK UI Kit comes with various high- and low-level components supporting core use cases around the HERE Mobile SDK. Along with these components we deliver a rich set of supportive controls and tailored data structures to further reduce your development cost. All components can be freely arranged in your layouts and are highly customizable. More components will be delivered as part of the next releases. We already provide UI-centric support for the following features: +The HERE Mobile SDK UI Kit (MSDKUI) comes with various high- and low-level components supporting core use cases around the HERE Mobile SDK. Along with these components we deliver a rich set of supportive controls and tailored data structures to further reduce your development cost. All components can be freely arranged in your layouts and are highly customizable. More components will be delivered as part of the next releases. We already provide UI-centric support for the following features: ##### Route Planner - Waypoint list (start, stop, incl. support for stopovers, drag & drop sorting) @@ -59,7 +59,7 @@ The HERE Mobile SDK UI Kit is already fully localized for the following language - Vietnamese ## Supported platforms -The HERE Mobile SDK UI Kit components are available for Android and [iOS](https://github.com/heremaps/msdkui-ios). The required HERE Mobile SDK is Version 3.15, only the _Premium edition_ is supported. The HERE Mobile SDK UI Kit supports scooter routing. Please, make sure to extend your license key if you want to include scooter routing in your app. +The HERE Mobile SDK UI Kit (MSDKUI) components are available for Android and [iOS](https://github.com/heremaps/msdkui-ios). The required HERE Mobile SDK is Version 3.15, only the _Premium edition_ is supported. The HERE Mobile SDK UI Kit supports scooter routing. Please, make sure to extend your license key if you want to include scooter routing in your app. **Android Environment** - Minimum supported API version is 19 (KitKat), allowing you to reach more than 95% of all Android devices. @@ -68,7 +68,7 @@ The HERE Mobile SDK UI Kit components are available for Android and [iOS](https: - [AndroidX](https://developer.android.com/jetpack/androidx) is required. ## Quick Start -Please have a look at our [Quick Start](Documentation/Guides/QuickStart.md) tutorial to see how easy it is to integrate the HERE Mobile SDK UI Kit into your own apps. More information on how to use the HERE Mobile SDK UI Kit can be found in our [User Guide](Documentation/Guides/UserGuide.md). Information on how to contribute to this project can be found in our [Contribution Guide](Documentation/Guides/ContributionGuide.md). +Please have a look at our [Quick Start](Documentation/Guides/QuickStart.md) tutorial to see how easy it is to integrate the HERE Mobile SDK UI Kit (MSDKUI) into your own apps. More information on how to use the HERE Mobile SDK UI Kit (MSDKUI) can be found in our [User Guide](Documentation/Guides/UserGuide.md). Information on how to contribute to this project can be found in our [Contribution Guide](Documentation/Guides/ContributionGuide.md). ## Documentation - The latest API Reference can be found [here](https://heremaps.github.io/msdkui-android/). @@ -77,7 +77,7 @@ Please have a look at our [Quick Start](Documentation/Guides/QuickStart.md) tuto - A more complex and fully functional _demo app_ can be found in this repository. ## Get in Touch -We are happy to hear your feedback. Please [contact us](https://developer.here.com/contact-us) for any questions, suggestions or improvements. Thank you for your using the HERE Mobile SDK UI Kit. +We are happy to hear your feedback. Please [contact us](https://developer.here.com/contact-us) for any questions, suggestions or improvements. Thank you for your using the HERE Mobile SDK UI Kit (MSDKUI). ## License Copyright (c) 2017-2020 HERE Europe B.V.