Skip to content

Latest commit

 

History

History
409 lines (305 loc) · 12.7 KB

README.md

File metadata and controls

409 lines (305 loc) · 12.7 KB
Raw

MaterialDrawerKt

Build Status Bintray Awesome Kotlin Badge Android Arsenal

Create navigation drawers in your Activities and Fragments without having to write any XML, in pure Kotlin code, with access to all the features of the original library: all sorts of menu items, badges, account headers, and more.

This library is a Kotlin DSL wrapper around the mikepenz/MaterialDrawer library, and features:

  • Access to all of the original library's features with a nice, concise API
  • Fixes for the couple of inconsistencies of the original API
  • Detailed code comments for conveninent in-IDE documentation lookup (Ctrl+Q on Windows, ⌃J on Mac)

Sample app

You can find the sample app in the Play Store, and its source code in the app module of the project.

Setup

The library is hosted on mavenCentral(). To use it, add the following to your module level build.gradle file's dependencies:

implementation 'co.zsmb:materialdrawer-kt:3.0.0'

// required support lib modules
implementation "androidx.appcompat:appcompat:${versions.appcompat}"
implementation "androidx.recyclerview:recyclerview:${versions.recyclerView}"
implementation "androidx.annotation:annotation:${versions.annotation}"
implementation "com.google.android.material:material:${versions.material}"
implementation "androidx.constraintlayout:constraintlayout:${versions.constraintLayout}"

In general, you don't have to include the original library separately. (See the note in the FAQ.)

If you want to use the pre-Kotlin version of the base library for some reason, you can use the last 2.x release of the library found here.

If you're not using AndroidX yet, you can use the last 1.x release of the library found here.

Basic usage

Just as a general note, try using the in-IDE documentation when you're in doubt about anything. It's much more detailed than the original library's docs, this was one of the design goals of the library. The IntelliJ/Android Studio shortcut for bringing up the docs about a function is Ctrl+Q on Windows, and ⌃J on Mac.

To add a navigation drawer, you just have to add the following to your Activity's onCreate function:

drawer {}

This will give you an empty sheet that you can drag in from the left side of the screen. You can add menu items to it like this:

drawer {
    primaryItem("Home") {}
    divider {}
    primaryItem("Users") {}
    secondaryItem("Settings") {}
}

For all the available types of menu items, see the "Drawer item types" in the sample app.

You can modify properties of the drawer inside the drawer {} block, and properties of the menu items in their respective blocks:

drawer {
    headerViewRes = R.layout.header
    closeOnClick = false
    
    primaryItem("Home") {
        icon = R.drawable.ic_home
    }
    divider {}
    primaryItem("Users") {
        icon = R.drawable.ic_user
    }
    secondaryItem("Settings") {
        icon = R.drawable.ic_settings
        selectable = false
    }
}

Note that most of these properties are non-readable, and can only be used for setting these values. This is why these properties are marked as deprecated, and will cause build errors. The rest should be safe to use to read back any values you've set, if you had to do that for whatever reason.

For a complete reference of the wrapper methods and properties, see the list in the wiki.

Advanced features

Account headers

Creating an account header with profile entries can be done like so:

drawer {
    accountHeader { 
        profile("Samantha", "samantha@gmail.com") {
            icon = "http://some.site/samantha.png"
        }
        profile("Laura", "laura@gmail.com") { 
            icon = R.drawable.profile_laura
        }
    }
    
    primaryItem("Home")
}

Note that loading images from URLs requires additional setup, see the Image loading section of this document or the DrawerApplication class in the sample app for guidance.

Footers

You can add items to an always visible, sticky footer in by nesting them inside a footer block:

drawer {
    footer {
        primaryItem("Primary item")
        secondaryItem("Secondary item")
    }
}

Listeners

Listeners can be added to both individual drawer items and the entire drawer. Some examples:

drawer {
    primaryItem("Item 1")
    primaryItem("Item 2") {
        // Called only when this item is clicked
        onClick { _ ->
            Log.d("DRAWER", "Click.")
            false
        }
    }

    // Called when any drawer item is clicked
    onItemClick { _, position, _ ->
        Log.d("DRAWER", "Item $position clicked")
        false
    }
    
    onOpened { 
        Log.d("DRAWER", "Navigation drawer opened")
    }
}

More examples in the "Listeners" section of the sample app.

Badges

Add badges to drawer items, and customize them with this syntax:

drawer {
    primaryItem {
        badge("111") {
            cornersDp = 0
            color = 0xFF0099FF
            colorPressed = 0xFFCC99FF
        }
    }
}

You can see more examples in the "Badges" section of the sample app.

Conversion from original

This is a rough guide to how the original API's features are converted to the DSL, for those who are already familiar with the original library.

Builders

Builders are replaced by functions that are named without the "Builder" suffix.

DrawerBuilder()
    .withActivity(this)
    .build()

... is replaced with ...

drawer { 

}

DrawerItems

Calls to XyzDrawerItem classes are replaced with functions as well. The "Drawer" word is omitted from the function's name. Note that properties like names and descriptions of the drawer items become parameters of these functions.

For example:

PrimaryDrawerItem().withName("Item name")

... is replaced with ...

primaryItem("Item name") {

}

with functions

Calls to .withXyz() functions are replaced with properties that you can set. For a complete reference of the wrapper methods and properties, see the list in the wiki.

Very few of these are readable. If you want to read these at build time for some reason, check the documentation. Non-readable properties should be deprecated and not compile, but if they do, they will throw a NonReadablePropertyException if you attempt to read their value.

For an example...

AccountHeaderBuilder()
    .withActivity(this)
    .withHeaderBackground(R.color.colorPrimary)
    .build()

... is replaced with ...

accountHeader {
    headerBackgroundRes = R.color.colorPrimary 
}

Note that overloaded functions are replaced with multiple properties, distinguished by suffixes. For example, the above withHeaderBackground function's three overloads can be set through the following properties:

Parameter type Property name
Int headerBackground
headerBackgroundRes
Drawable headerBackgroundDrawable
ImageHolder headerBackgroundImage

There may be defaults without suffixes for what's assumed to be the most popular use case.

Listeners

Adding simple listeners to drawers (or individual drawer items) are done with onXyz function calls, which take lambdas as parameters. For example:

DrawerBuilder()
        .withActivity(this)
        .withOnDrawerItemClickListener(object : Drawer.OnDrawerItemClickListener {
            override fun onItemClick(view: View, position: Int, drawerItem: IDrawerItem<out Any?, out RecyclerView.ViewHolder>?): Boolean {
                Log.d("DRAWER", "Clicked!")
                return true
            }
        })
        .build()

... is replaced with ...

drawer {
    onItemClick { view, position, drawerItem -> 
        Log.d("DRAWER", "Clicked!")
        true
    }
}

Complex listeners

Listeners that originally have multiple callbacks have been broken up into individual functions:

DrawerBuilder()
        .withActivity(this)
        .withOnDrawerListener(object : Drawer.OnDrawerListener {
            override fun onDrawerSlide(drawerView: View?, slideOffset: Float) {
                Log.d("DRAWER", "Sliding")
            }

            override fun onDrawerClosed(drawerView: View?) {
                Log.d("DRAWER", "Closed")
            }

            override fun onDrawerOpened(drawerView: View?) {
                Log.d("DRAWER", "Opened")
            }
        })
        .build()

... is replaced with ...

drawer { 
    onSlide { _, _ ->
        Log.d("DRAWER", "Sliding")
    }
    onClosed {
        Log.d("DRAWER", "Closed")
    }
    onOpened {
        Log.d("DRAWER", "Opened")
    }
}

Image loading

Since the MaterialDrawer library doesn't include its own image loading solution, you have to set one up yourself. You have to do this before the first time MaterialDrawer has to load an image, for example, in your Application's onCreate method.

With the original library, this setup looks like this (Picasso is just used as an example):

DrawerImageLoader.init(object: AbstractDrawerImageLoader() {
    override fun placeholder(ctx: Context, tag: String?): Drawable {
        return DrawerUIUtils.getPlaceHolder(ctx)
    }

    override fun set(imageView: ImageView, uri: Uri, placeholder: Drawable?, tag: String?) {
        Picasso.with(imageView.context)
                .load(uri)
                .placeholder(placeholder)
                .into(imageView)
    }

    override fun cancel(imageView: ImageView) {
        Picasso.with(imageView.context)
                .cancelRequest(imageView)
    }
})

This can be replaced by the following:

drawerImageLoader {
    placeholder { ctx, tag ->
        DrawerUIUtils.getPlaceHolder(ctx)
    }
    set { imageView, uri, placeholder, tag ->
        Picasso.with(imageView.context)
                .load(uri)
                .placeholder(placeholder)
                .into(imageView)
    }
    cancel { imageView ->
        Picasso.with(imageView.context)
                .cancelRequest(imageView)
    }
}

FAQ

I want to use features of the base library that haven't made it to this one yet

If the base library gets features and they aren't ported to this wrapper yet, you can include that as a dependency in addition to this one, and use the two together. For these purposes, the internal DrawerBuilder that this library uses is exposed through a property, and you can access it like so:

drawer {
    builder.withKeepStickyItemsVisible(true)
}

The internal AccountHeaderBuilder is exposed in the same way:

accountHeader {
    builder.withHeightDp(20)
}

As for drawer items, you can just use the original API's calls on the items that are returned:

val item = primaryItem("Hello") {
    icon = R.drawable.profile
}
item.withBadge("10")
primaryItem("Hello") {
    icon = R.drawable.profile
}.withBadge("10")

License

Copyright 2020 Marton Braun

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.