acolombo11 / minimap-view

📟 A minimap view library for Android to help the user orienting himself around a big RecyclerView

minimap-view

A minimap view library for Android RecyclerView.

The miniature map is usually placed in the corner of the screen, to help the user in orienting himself in a screen with a big scrolling view. Check the example by cloning the repo and starting the demo app, or by downloading the Release APK.

The example shown in the demo app is a resizable parking lot, showing a few scenarios of the library responding to resizes:

Download  

Add the dependency in your app build.gradle with the current version number:

implementation 'eu.acolombo:minimap-view:1.0.3'

Add JitPack in your root build.gradle:

allprojects {
    repositories {
        ..
        maven { url 'https://jitpack.io' }
    }
}

Another option is to copy the single file MinimapView.kt directly in your project.

Usage

Add the minimap in your layout customizing the properties you need:

XML

<eu.acolombo.minimap.MinimapView
    android:id="@+id/minimapView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_margin="@dimen/activity_margin"
    app:minimapBackgroundColor="@color/colorMinimap"
    app:minimapBorderWidth="3dp"
    app:minimapCornerRadius="5dp"
    app:minimapMaxSize="160dp"/>

Then link it to your RecyclerView:

Kotlin

recyclerView.minimap(minimapView)

Java

MinimapView minimapView = findViewById(R.id.minimapView)
minimapView.setRecyclerView(recyclerView)

For the library to work properly, the LayoutManager used in your RecyclerView should implement computeHorizontalScrollRange and computeVerticalScrollRange, not all LayoutManagers do by default.

Docs

The MinimapView indicator matches the size of the visible area of the RecycleView, while its background matches the size of the scrollable area of the RecyclerView. Both parts of the MinimapView will auto-update when the RecyclerView visible size or scrollable size will change. The calculations to have the indicator and the background match all the possible cases are not that trivial. To keep ratios and positions correct, there are many different scenarios you have to think about, for example when the size of the RecyclerView is bigger than its scrollable area. So I made a scheme with all the measurement names:

State

For the moment the library lets you select one max size, and the MinimapView width or height will have to stay inside that size, keeping its form factor. Instead of one max size, having both a max-height and a max-width would be ideal. Also it would be cool to support not only RecyclerView but other scrolling views.

Thanks

• Devunwired for the Layout Manager used in the example app
• Freepik for the vector graphics used in the example app

Projects using minimap-view

• mywellness: Dark theme, Light theme
• Let me know if you're using it in you project