MaterialDrawer README

The project's README from github.com/mikepenz/MaterialDrawer. As one markdown file: README.md.

MaterialDrawer

... the flexible, easy to use, all in one drawer library for your Android project.

What's included 🚀 • Setup 🛠️ • Migration Guide 🧬 • WIKI / FAQ 📖 • Used by • Sample App

What's included 🚀

If you upgrade from < 8.0.0 follow the MIGRATION GUIDE

Preview

Screenshots 🎉

Image

Setup

Latest releases 🛠

1. Provide the gradle dependency

The latest release is available on Maven Central.

implementation("com.mikepenz:materialdrawer:${latestRelease}")

//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:1.5.0-alpha05" // requires at least 1.5.0-x
implementation "androidx.constraintlayout:constraintlayout:${versions.constraintLayout}"

NavController Support @ Maven Central.

// Add for NavController support
implementation "com.mikepenz:materialdrawer-nav:${lastestMaterialDrawerRelease}"

Android-Iconics Support @ Maven Central .

// Add for Android-Iconics support
implementation "com.mikepenz:materialdrawer-iconics:${lastestMaterialDrawerRelease}"

2. Add the Drawer into the XML

The MaterialDrawerSliderView has to be provided as child of the DrawerLayout and will as such act as the slider

<androidx.drawerlayout.widget.DrawerLayout xmlns : android ="http://schemas.android.com/apk/res/android"
xmlns:app = "http://schemas.android.com/apk/res-auto"
android:id = "@+id/root"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:fitsSystemWindows="true">

    ... your content ...

    <com.mikepenz.materialdrawer.widget.MaterialDrawerSliderView
        android:id="@+id/slider"
        android:layout_width="wrap_content"
        android:layout_height="match_parent"
        android:layout_gravity="start"
        android:fitsSystemWindows="true" />
</androidx.drawerlayout.widget.DrawerLayout>

3. Add the DrawerStyle to your theme

<style name="SampleApp.DayNight" parent="Theme.Material3.DayNight.NoActionBar">
    ...
    <item name="materialDrawerStyle">@style/Widget.MaterialDrawerStyle</item>
    <item name="materialDrawerHeaderStyle">@style/Widget.MaterialDrawerHeaderStyle</item>
    ...
</style>

Great. Your drawer is now ready to use.

Note

Using v9.x with Material 3 theming requires a Material3 theme as base for the activity.

Additional Setup

Add items and adding some functionality

//if you want to update the items at a later time it is recommended to keep it in a variable
val item1 = PrimaryDrawerItem().apply { nameRes = R.string.drawer_item_home; identifier = 1 }
val item2 = SecondaryDrawerItem().apply { nameRes = R.string.drawer_item_settings; identifier = 2 }

// get the reference to the slider and add the items
slider.itemAdapter.add(
	    item1,
	    DividerDrawerItem(),
	    item2,
	    SecondaryDrawerItem().apply { nameRes = R.string.drawer_item_settings }
)

// specify a click listener
slider.onDrawerItemClickListener = { v, drawerItem, position ->
    // do something with the clicked item :D
    false
}

Selecting an item

//set the selection to the item with the identifier 1
slider.setSelection(1)
//set the selection to the item with the identifier 2
slider.setSelection(item2)
//set the selection and also fire the `onItemClick`-listener
slider.setSelection(1, true)

By default, when a drawer item is clicked, it becomes the new selected item. If this isn't the expected behavior, you can disable it for this item using isSelectable = false:

SecondaryDrawerItem().apply { nameRes = R.string.drawer_item_dialog; isSelectable = false }

Modify items or the drawer

//modify an item of the drawer
item1.apply {
  nameText = "A new name for this drawerItem"; badge = StringHolder("19")
  badgeStyle = BadgeStyle().apply { textColor = ColorHolder.fromColor(Color.WHITE); color = ColorHolder.fromColorRes(R.color.md_red_700) }
}
//notify the drawer about the updated element. it will take care about everything else
slider.updateItem(item1)

//to update only the name, badge, icon you can also use one of the quick methods
slider.updateName(1, "A new name")

//the result object also allows you to add new items, remove items, add footer, sticky footer, ..
slider.addItem(DividerDrawerItem())
slider.addStickyFooterItem(PrimaryDrawerItem().apply { nameTest = "StickyFooter" })

//remove items with an identifier
slider.removeItem(2)

//open / close the drawer
slider.drawerLayout?.openDrawer(slider)
slider.drawerLayout?.closeDrawer(slider)

//get the reference to the `DrawerLayout` itself
slider.drawerLayout

Add profiles and an AccountHeader

// Create the AccountHeader
headerView = AccountHeaderView(this).apply {
    attachToSliderView(slider) // attach to the slider
    addProfiles(
        ProfileDrawerItem().apply { nameText = "Mike Penz"; descriptionText = "[email protected]"; iconRes = R.drawable.profile; identifier = 102 }
    )
    onAccountHeaderListener = { view, profile, current ->
        // react to profile changes
        false
    }
    withSavedInstance(savedInstanceState)
}

Android-Iconics support

The MaterialDrawer provides an extension for the Android-Iconics library. This allows you to create your DrawerItems with an icon from any font.

Choose the fonts you need. Available Fonts

// Add for Android-Iconics support
implementation "com.mikepenz:materialdrawer-iconics:${lastestMaterialDrawerRelease}"

// fonts
implementation 'com.mikepenz:google-material-typeface:x.y.z@aar' //Google Material Icons
implementation 'com.mikepenz:fontawesome-typeface:x.y.z@aar'     //FontAwesome

//now you can simply use any icon of the Google Material Icons font
PrimaryDrawerItem().apply { iconicsIcon = GoogleMaterial.Icon.gmd_wb_sunny }
//Or an icon from FontAwesome
SecondaryDrawerItem().apply { iconicsIcon = FontAwesomeBrand.Icon.fab_github }

Advanced Setup

For advanced usecases. Please have a look at the provided sample activities.

Load images via url

The MaterialDrawer supports fetching images from URLs and setting them for the Profile icons. As the MaterialDrawer does not contain an ImageLoading library the dev can choose his own implementation (Picasso, Glide, ...). This has to be done, before the first image should be loaded via URL. (Should be done in the Application, but any other spot before loading the first image is working too)

//initialize and create the image loader logic
DrawerImageLoader.init(object : AbstractDrawerImageLoader() {
    override fun set(imageView: ImageView, uri: Uri, placeholder: Drawable) {
        Picasso.get().load(uri).placeholder(placeholder).into(imageView)
    }

    override fun cancel(imageView: ImageView) {
        Picasso.get().cancelRequest(imageView)
    }
    
    /*
    override fun set(imageView: ImageView, uri: Uri, placeholder: Drawable, tag: String?) {
        super.set(imageView, uri, placeholder, tag)
    }

    override fun placeholder(ctx: Context): Drawable {
        return super.placeholder(ctx)
    }

    override fun placeholder(ctx: Context, tag: String?): Drawable {
        return super.placeholder(ctx, tag)
    }
    */
})

An implementation with GLIDE v4 (See tag v6.1.1 for glide v3 sample) can be found in the sample application

JVM Target 1.8

// Since 8.1.0 the drawer includes core ktx 1.3.0 which requires jvm 1.8
kotlinOptions {
    jvmTarget = "1.8"
}

Style the drawer 🖌️

Custom style - styles.xml

Create your custom style. If you don't need a custom theme see the next section, how you can set the colors just by overwriting the original colors.

// define a custom drawer style
<style name="Widget.MaterialDrawerStyleCustom" parent="Widget.MaterialDrawerStyle">
    <item name="materialDrawerInsetForeground">#4000</item>
    <!-- MaterialDrawer specific values -->
    <item name="materialDrawerBackground">?colorSurface</item>
    <item name="materialDrawerPrimaryText">@color/color_drawer_item_text</item>
    <item name="materialDrawerPrimaryIcon">@color/color_drawer_item_text</item>
    <item name="materialDrawerSecondaryText">@color/color_drawer_item_text</item>
    <item name="materialDrawerSecondaryIcon">@color/color_drawer_item_text</item>
    <item name="materialDrawerDividerColor">?colorOutline</item>
    <item name="materialDrawerSelectedBackgroundColor">?colorSecondaryContainer</item>
</style>

// define a custom header style
<style name="Widget.MaterialDrawerHeaderStyleCustom" parent="">
    <item name="materialDrawerCompactStyle">true</item>
    <item name="materialDrawerHeaderSelectionText">?colorOnSurface</item>
    <item name="materialDrawerHeaderSelectionSubtext">?colorOnSurface</item>
</style>

// define the custom styles for the theme
<style name="SampleApp" parent="Theme.Material3.Light.NoActionBar">
    ...
    <item name="materialDrawerStyle">@style/Widget.MaterialDrawerStyleCustom</item>
    <item name="materialDrawerHeaderStyle">@style/Widget.MaterialDrawerHeaderStyleCustom</item>
    ...
</style>

Adjust BezelImageView style

Overwrite the Style of the BezelImageView for the whole MaterialDrawer

<style name="BezelImageView">
    <item name="biv_maskDrawable">@drawable/material_drawer_rectangle_mask</item>
    <item name="biv_drawCircularShadow">false</item>
    <item name="biv_selectorOnPress">@color/material_drawer_primary</item>
    <item name="android:scaleType">centerInside</item>
</style>

Used by

(feel free to send me new projects)

Articles about the MaterialDrawer

Credits

Developed By

License

Copyright 2021 Mike Penz

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.

MaterialDrawer (mikepenz/MaterialDrawer)

Searching Database…

11.6K ·GitHub
MaterialDrawer
这是什么？MaterialDrawer 是一个开源的 Android 库，可以为你的应用添加灵活的导航抽屉——这是一套遵循 Google Material Design 规范的一站式抽屉解决方案，在 GitHub 上获得了超过 11000 颗星。
这是一个成品应用，还是要加到我自己项目里的东西？它是一个库，需要作为依赖添加到你自己的 Android 项目中，而不是一个独立的应用。抽屉基于 RecyclerView 构建，通过一个快捷简单的 API 进行配置。
怎么把它加到我的 Android 项目里？按照 README 中 Setup 部分的说明，把它作为 Gradle 或 Maven 依赖添加进去。该库基于 AndroidX 支持库构建，你在代码里用抽屉条目组装出抽屉。
在旧款 Android 设备上能用吗？可以——它最低兼容 API Level 16，也就是 Android 4.1 及更高版本，并通过 AndroidX 支持库来工作。
升级或使用 Material 3 主题时有什么坑吗？有——从 v9.x 升级时，Material 3 主题要求你的 Activity 以 Material3 主题作为基础主题，所以要提前规划好应用的主题设置。
有哪些应用在实际使用它？已上架应用的名单很长：Tusky 和 Pachli（Mastodon 客户端）、Boost for reddit、Calendula、MLManager、Meldmail、Recipedia 等等，README 的 Used by 部分列出了几十个。
可以免费在自己的应用里用吗？可以——它采用 Apache License 2.0 许可证（版权归属 Mike Penz），在个人和商业应用中都可以免费使用。
开箱即用有哪些功能？包括 AccountSwitcher 和账户头部、多个默认抽屉条目、可展开的条目、角标（badge）支持、吸顶或吸底的头部和底部、RTL 支持、类似 Gmail 的 MiniDrawer，以及对 NavController 的支持。
抽屉图标可以用哪些？通过 Android-Iconics 集成可以使用矢量 .svg 图标和图标字体——包括 Google Material Design Icons、Google Material Community icons、FontAwesome 等等。
头像图片能从 URL 加载吗？可以，但这个库本身不带图片加载组件——你需要自己接入一个，比如 Picasso 或 Glide，在第一张图片加载之前完成，最好放在 Application 类里。
抽屉的外观可以自定义到什么程度？空间很大：它自带多种主题，有助于保持你自己的主题简洁；你可以在运行时修改颜色，还可以覆盖 styles.xml 或 BezelImageView 样式来做更深入的定制。
What are similar projects?material-components-android, SlidingMenu, FlycoTabLayout, AppIntro, AndroidSwipeLayout, QMUI_Android, material-dialogs, banner
Which topics is it in?material-theme, material-components, material-ui, android-ui, androidx, android-development, android-library, material-design, themes, mobile-development, theme, kotlin
Creator
mikepenz
Size
22.7 MB
Stars
11.6K
Updated
CommitOct 14Releasev9.0.2Aug 15
Age
11y
Commits · 90 Days