Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/anggrayudi/materialpreference
⚙️ A library designed to replace default preferences on Android framework with something beauty.
https://github.com/anggrayudi/materialpreference
android android-library android-preference android-settings kotlin material-design material-preference
Last synced: about 2 months ago
JSON representation
⚙️ A library designed to replace default preferences on Android framework with something beauty.
- Host: GitHub
- URL: https://github.com/anggrayudi/materialpreference
- Owner: anggrayudi
- License: apache-2.0
- Created: 2018-06-30T15:14:16.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-31T17:04:04.000Z (almost 2 years ago)
- Last Synced: 2024-05-21T06:36:47.380Z (7 months ago)
- Topics: android, android-library, android-preference, android-settings, kotlin, material-design, material-preference
- Language: Kotlin
- Homepage:
- Size: 3.99 MB
- Stars: 114
- Watchers: 7
- Forks: 19
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Material Preference
[](https://github.com/anggrayudi/MaterialPreference/actions?query=workflow%3A%22Android+CI%22)
A library designed for people who love simplicity. Hate the old preference style? Try this library.
It combines libraries from `androidx.preference` and `net.xpece.android.support.preference`.
Available from API 17.
## Screenshots
## Note
Even though Material Preference is built in Kotlin, but you can use this library in Java with a little setup in your `build.gradle`. Read section [Java compatibility support](https://github.com/anggrayudi/MaterialPreference#java-compatibility-support).
## Usage
### Basic
```gradle
android {
// add these lines
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
implementation 'com.anggrayudi:materialpreference:X.Y.Z'
}
```
Where `X.Y.Z` is the library version: 
Snapshots can be found [here](https://oss.sonatype.org/#nexus-search;quick~com.anggrayudi).
To use SNAPSHOT version, you need to add this URL to the root Gradle:
```gradle
allprojects {
repositories {
google()
// add this line
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
}
}
```
**Note:** Since v3.5.0, we only distribute this library through [OSS Sonatype Maven](https://oss.sonatype.org/#nexus-search;quick~com.anggrayudi).
Distributing it on Bintray became more difficult because Bintray seem lazy to maintain their [Gradle Plugin](https://github.com/bintray/gradle-bintray-plugin/).
From your [`preferences.xml`](https://github.com/anggrayudi/MaterialPreference/blob/master/sample/src/main/res/xml/preferences.xml):
```xml
```
From your [`SettingsFragment`](https://github.com/anggrayudi/MaterialPreference/blob/master/sample/src/main/java/com/anggrayudi/materialpreference/sample/SettingsFragment.kt):
```kotlin
class SettingsFragment : PreferenceFragmentMaterial() {
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
addPreferencesFromResource(R.xml.preferences)
}
companion object {
fun newInstance(rootKey: String?) = SettingsFragment().apply {
arguments = Bundle().also {
it.putString(PreferenceFragmentMaterial.ARG_PREFERENCE_ROOT, rootKey)
}
}
}
}
```
From your [`SettingsActivity`](https://github.com/anggrayudi/MaterialPreference/blob/master/sample/src/main/java/com/anggrayudi/materialpreference/sample/SettingsActivity.kt):
```kotlin
class SettingsActivity : PreferenceActivityMaterial() {
private var settingsFragment: SettingsFragment? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_settings)
if (savedInstanceState == null) {
settingsFragment = SettingsFragment.newInstance(null)
supportFragmentManager.beginTransaction().add(R.id.fragment_container, settingsFragment!!, TAG).commit()
} else {
onBackStackChanged()
}
}
override fun onBuildPreferenceFragment(rootKey: String?): PreferenceFragmentMaterial {
return SettingsFragment.newInstance(rootKey)
}
override fun onBackStackChanged() {
settingsFragment = supportFragmentManager.findFragmentByTag(TAG) as SettingsFragment
title = settingsFragment!!.preferenceFragmentTitle
}
}
```
### Preference Migration
During app development, you may encounter a condition where you need to modify your current `SharedPreferences`, such as renaming a preference's key.
Material Preference v3.4.0 introduces a new feature called Preference Migration.
Define your migration plan by implementing `PreferenceMigration` interface:
```kotlin
class MyPreferenceMigration : PreferenceMigration {
override fun migrate(plan: MigrationPlan, currentVersion: Int) {
// Implement your migration plan here.
// Read sample code in class App.kt for more information.
}
override fun onMigrationCompleted(preferences: SharedPreferences) {
}
companion object {
const val PREFERENCE_VERSION = 3
}
}
```
Finally, start the migration:
```kotlin
PreferenceMigration.setupMigration(MyPreferenceMigration(), preferences, PREFERENCE_VERSION)
```
### Preference Key Constants Generator
Material Preference has a capability to auto-generate your preference keys in a constant class. By default, this class is named `PrefKey`. With this generator, you don't need to rewrite constant field each time you modify preference key from file `res/xml/preferences.xml`. It improves accuracy in writing constant values.
To enable this feature, simply add the following configuration to your `build.gradle`:
````gradle
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-kapt' // Add this line
dependencies {
implementation 'com.anggrayudi:materialpreference:3.x.x'
kapt 'com.anggrayudi:materialpreference-compiler:1.8'
}
````
From your `SettingsFragment` class:
````kotlin
@PreferenceKeysConfig // Add this annotation
class SettingsFragment : PreferenceFragmentMaterial() {
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
addPreferencesFromResource(R.xml.preferences)
// You can access the constant values with auto-generated class named PrefKey
findPreference(PrefKey.ABOUT)?.summary = BuildConfig.VERSION_NAME
val volume = findPreferenceAs(PrefKey.NOTIFICATION_VOLUME)
volume?.summaryFormatter = { "$it%" }
}
}
````
**Note:**
* If `PrefKey` does not update constant fields, click  Make Project in Android Studio.
* This generator wont work with Android Studio 3.3.0 Stable, 3.4 Beta 3, and 3.5 Canary 3 because of [this bug](https://issuetracker.google.com/issues/122883561). The fixes are available in the next version of Android Studio.
### SharedPreferencesHelper
Since v3.5.0, the annotation processor will generate `SharedPreferencesHelper`, so you don't need to retrieve `SharedPreferences` value like this: `SharedPreferences.get(key, defaultValue)`.
Take advantage of using it with dependency injection such as [Dagger 2](https://github.com/google/dagger) and [Koin](https://github.com/InsertKoinIO/koin).
Personally, I would recommend you to use Koin because of its simplicity.
```kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// ...
val preferencesHelper = SharedPreferencesHelper(this)
setTitle(preferencesHelper.accountName)
}
}
```
From above code, `accountName` is a generated method based on your configuration on `preferences.xml`.
It takes `android:defaultValue` if method `accountName` can't find any value stored in the `SharedPreferences`.
You can customize the method name via `app:helperMethodName="yourMethodName"`. Read our sample code for more information.
#### Example
From your [`SettingsFragment.java`](https://github.com/anggrayudi/MaterialPreference/blob/master/sample/src/main/java/com/anggrayudi/materialpreference/sample/java/SettingsFragment.java):
````java
@PreferenceKeysConfig
public class SettingsFragment extends PreferenceFragmentMaterial {
@Override
public void onCreatePreferences(@Nullable Bundle savedInstanceState, @Nullable String rootKey) {
addPreferencesFromResource(R.xml.preferences);
Preference preferenceAbout = findPreference(PrefKey.ABOUT);
preferenceAbout.setSummary(BuildConfig.VERSION_NAME);
SeekBarDialogPreference vibration = (SeekBarDialogPreference) findPreference(PrefKey.VIBRATE_DURATION);
// summary formatter example
vibration.setSummaryFormatter(new Function1() {
@Override
public String invoke(Integer duration) {
return duration + "ms";
}
});
IndicatorPreference indicatorPreference = (IndicatorPreference) findPreference(PrefKey.ACCOUNT_STATUS);
// click listener example
indicatorPreference.setOnPreferenceClickListener(new Function1() {
@Override
public Boolean invoke(Preference preference) {
new MaterialDialog(getContext())
.message(null, "Your account has been verified.", false, 1f)
.positiveButton(android.R.string.ok, null, null)
.show();
return true;
}
});
// long click listener example
indicatorPreference.setOnPreferenceLongClickListener(new Function1() {
@Override
public Boolean invoke(Preference preference) {
Toast.makeText(getContext(), "onLogClick: " + preference.getTitle(), Toast.LENGTH_SHORT).show();
return true;
}
});
}
}
````
From your [`SettingsActivity.java`](https://github.com/anggrayudi/MaterialPreference/blob/master/sample/src/main/java/com/anggrayudi/materialpreference/sample/java/SettingsActivity.java):
````java
public class SettingsActivity extends PreferenceActivityMaterial {
private static final String TAG = "Settings";
private SettingsFragment settingsFragment;
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_settings);
setSupportActionBar(findViewById(R.id.toolbar));
getSupportActionBar().setDisplayHomeAsUpEnabled(true);
if (savedInstanceState == null) {
settingsFragment = SettingsFragment.newInstance(null);
getSupportFragmentManager().beginTransaction()
.add(R.id.fragment_container, settingsFragment, TAG)
.commit();
} else {
onBackStackChanged();
}
}
@NotNull
@Override
protected PreferenceFragmentMaterial onBuildPreferenceFragment(@Nullable String rootKey) {
return SettingsFragment.newInstance(rootKey);
}
@Override
public void onBackStackChanged() {
settingsFragment = (SettingsFragment) getSupportFragmentManager().findFragmentByTag(TAG);
setTitle(settingsFragment.getPreferenceFragmentTitle());
}
}
````
## Preferences
- `Preference`
- `CheckBoxPreference`
- `SwitchPreference`
- `EditTextPreference`
- `ListPreference`
- `IntegerListPreference`
- `MultiSelectListPreference`
- `SeekBarDialogPreference`
- `SeekBarPreference`
- `RingtonePreference`
- `IndicatorPreference`
- `FolderPreference`
- `DatePreference`
- `TimePreference`
- `ColorPreference`
### RingtonePreference
`RingtonePreference` will show only system ringtone sounds by default.
If you want to include sounds from the external storage your app needs to request
`android.permission.READ_EXTERNAL_STORAGE` permission in its manifest.
Don't forget to check this runtime permission before opening ringtone picker on API 23.
## License
Copyright 2018-2022 Anggrayudi Hardiannicko A.
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.