Skip to content

Latest commit

 

History

History
396 lines (292 loc) · 15.5 KB

README.md

File metadata and controls

396 lines (292 loc) · 15.5 KB
Raw

BottomSheets

Android library designed to enrich your application with the beautiful stutter-free Material Design Bottom Sheets

BottomSheets will help you make your application more appealing to your end users with its sleek stutter-free implementation of the Material Bottom Sheets.

Download License Platform Android Arsenal

Contents

Demo

  • Demo Video
  • Screenshots

Getting Started

  1. Make sure that you've added the jcenter() repository to your top-level build.gradle file.
buildscript {
    //...
    repositories {
        //...
        jcenter()
    }
    //...
}
  1. Add the library dependency to your module-level build.gradle file.

Latest version: Download 

ext {
    //...
    bottomSheetsLibraryVersion = "1.0.0"
}

dependencies {
    //...
    implementation "com.arthurivanets.bottomsheet:bottomsheets-core:1.0.0"
}
  1. Enable the jetifier and androidX support in the top-level gradle.properties file.
//...
android.enableJetifier=true
android.useAndroidX=true
//....
  1. Update your compileSdkVersion in the module-level build.gradle file to 28+.
//...
android {
    //...
    compileSdkVersion 28
    //...
}
//...
  1. Update your com.android.support.appcompat.* dependency to the new androidx.appcompat.* alternative.
//...
dependencies {
    //...
    implementation "androidx.appcompat:appcompat:1.0.2"
    //...
}
//...
  1. Proceed with the implementation.

See: Structure, Basic Custom Implementation

Structure

The library is comprised of 3 modules, namely:

The first module - bottomsheets-core - is a base module the other modules depend on, it is the starting point for all of your custom bottom sheet implementations and is a required module. This module provides you with the base classes required for the bottom sheet implementation, such as the BaseBottomSheet.java which should be extended by your custom implementations of the bottom sheet and BottomSheet.java contract which exposes its supported public APIs, here you will also find the Config.java class which will help you customize the bottom sheet.

The second module - bottomsheets-sheets - is an optional module which includes the implementations of the most common bottom sheet types. Here you will find the ActionPickerBottomSheet.java, CustomActionPickerBottomSheet.java, as well as the coresponding configuration class - Config.java. This module depends on the bottomsheets-core and the Adapster library.

The third and last module - bottomsheets-ktx - is a collection of the extensions and general utils. Here you'll be able to find the BottomSheetsExtensions.kt which will simplify the creation of the common bottom sheet types in your Activities and Fragments. This module depends on the bottomsheets-core, bottomsheets-sheets and the Adapster library.

Basic Custom Implementation

IMPORTANT: In order to prevent the visual inconsistencies which might be caused by certain UI elements of the Application Theme, it is recommended that you specify the Application/Activity Theme without the Action Bar (any variant of the Theme.NoActionBar will suffice). You might also want to make your Status Bar translucent for more immersive experience.

In order to implement a basic custom bottom sheet you need to follow three simple steps:

  1. Create a new class and extend it from the BaseBottomSheet.java.
  2. Provide the custom content view for your bottom sheet in the onCreateSheetContentView(...).
  3. Use the created bottom sheet in your Activity/Fragment.

So, let's create a custom bottom sheet class - SimpleCustomBottomSheet and provide our own content view:

Kotlin (click to expand) 

class SimpleCustomBottomSheet(
    hostActivity : Activity,
    config : BaseConfig = Config.Builder(hostActivity).build()
) : BaseBottomSheet(hostActivity, config) {

    override fun onCreateSheetContentView(context : Context) : View {
        return LayoutInflater.from(context).inflate(
            R.layout.view_simple_custom_bottom_sheet,
            this,
            false
        )
    }

}


Java (click to expand) 

public class SimpleCustomBottomSheet extends BaseBottomSheet {

    public SimpleCustomBottomSheet(@NonNull Activity hostActivity) {
        this(hostActivity, new Config.Builder(hostActivity).build());
    }

    public SimpleCustomBottomSheet(@NonNull Activity hostActivity, @NonNull BaseConfig config) {
        super(hostActivity, config);
    }

    @NonNull
    @Override
    public final View onCreateSheetContentView(@NonNull Context context) {
        return LayoutInflater.from(context).inflate(
            R.layout.view_simple_custom_bottom_sheet,
            this,
            false
        );
    }

}


And now let's use the created SimpleCustomBottomSheet in our Activity:

Kotlin (click to expand) 

class MainActivity : AppCompatActivity() {

    private var bottomSheet : BaseBottomSheet? = null

    private fun showCustomBottomSheet() {
        //...
        bottomSheet = SimpleCustomBottomSheet(this).also(BottomSheet::show)
    }

}


Java (click to expand) 

public class MainActivity extends AppCompatActivity {

    private BottomSheet bottomSheet;

    private void showCustomBottomSheet() {
        //...
        bottomSheet = new SimpleCustomBottomSheet(this);
        bottomSheet.show();
    }

}


Action Picker Implementation

The implementation of the Action Picker Bottom Sheet becomes a trivial task with ActionPickerBottomSheet.java, as all you need to do here is simply provide a list of options and a bottom sheet configuration.

Let's use the ActionPickerBottomSheet.java in our Activity:

Kotlin (click to expand) 

class MainActivity : AppCompatActivity() {

    private var bottomSheet : BottomSheet? = null

    private fun showActionsBottomSheet() {
        bottomSheet = showActionPickerBottomSheet(
            options = getActionOptions(),
            onItemSelectedListener = OnItemSelectedListener {
                // do something...
            }
        )
    }

    fun getActionOptions() : List<Option> {
        // your options
    }

}


Java (click to expand) 

public class MainActivity extends AppCompatActivity {

    private BottomSheet bottomSheet;

    private void showActionsBottomSheet() {
        bottomSheet = BottomSheetsUtils.showActionPickerBottomSheet(
            this,
            getActionOptions(),
            new OnItemSelectedListener<Option>() {
                @Override
                public void onItemSelected(@NonNull Option item) {
                    // do something
                }
            }
        );
    }

    private List<Option> getActionOptions() {
        // your options
    }

}


Kotlin (click to expand) 

class MainActivity : AppCompatActivity() {

    private var bottomSheet : BottomSheet? = null

    private fun showActionsBottomSheet() {
        bottomSheet = ActionPickerBottomSheet.init(
            this,
            getActionOptions().map(::ActionItem),
            Config.Builder(this).build()
        )
        bottomSheet.setOnItemSelectedListener {
            // do something...
        }
        bottomSheet.show()
    }

    fun getActionOptions() : List<Option> {
        // your options
    }

}


Java (click to expand) 

public class MainActivity extends AppCompatActivity {

    private BottomSheet bottomSheet;

    private void showActionsBottomSheet() {
        bottomSheet = ActionPickerBottomSheet.init(
            this,
            getActionOptions(),
            new Config.Builder(this).build()
        );
        bottomSheet.setOnItemSelectedListener(new OnItemSelectedListener<ActionItem>() {
            @Override
            public void onItemSelected(@NonNull ActionItem item) {
                // do something
            }
        });
        bottomSheet.show();
    }

    private List<ActionItem> getActionOptions() {
        // your options wrapped into ActionItem(-s)
    }

}


Custom Action Picker Implementation

The implementation of the Custom Action Picker Bottom Sheet is not that much different from the Action Picker Implemenetation, you just need to use the CustomActionPickerBottomSheet.java instead of the ActionPickerBottomSheet.java in conjunction with your custom BaseActionItem-based Items and that's it.

See the example of a Custom Action Picker in Action.

Advanced Use

See the Sample app.

Contribution

See the CONTRIBUTING.md file.

Hall of Fame

Reminder
Owly

Using BottomSheets in your app and want it to get listed here? Email me at arthur.ivanets.work@gmail.com!

License

BottomSheets library is licensed under the Apache 2.0 License.