# KAU
Kotlin Android Utils
This library contains small helper functions used throughout almost all of my other projects. The goal is to make common interactions executable in a single line.
[Changelog](https://github.com/AllanWang/KAU/tree/master/docs/Changelog.md)
------------
KAU is available on JitPack
[](https://jitpack.io/#ca.allanwang/kau)
[](https://travis-ci.org/AllanWang/KAU)
[](https://raw.githubusercontent.com/AllanWang/KAU/master/LICENSE)
To apply, add the following to your root build.gradle:
```gradle
allprojects {
repositories {
...
maven { url "https://jitpack.io" }
}
}
```
And add the following dependencies (You can use a specific version, commit, or -SNAPSHOT):
```gradle
dependencies {
compile "ca.allanwang:kau:core:$KAU"
//Optional addition for image picker
compile "ca.allanwang:kau:imagepicker:$KAU"
}
```
-----------
# Features
* [KPrefs](#kprefs)
* [KPref Items](#kpref-items)
* [Changelog XML](#changelog)
* [Search View](#search-view)
* [Ripple Canvas](#ripple-canvas)
* [About Activity](#about-activity)
* [Timber Logger](#timber-logger)
* [Extensions](#extensions)
* [Email Builder](#email-builder)
## KPrefs
A typical SharedPreference contains items that look like so:
```Java
class MyPrefs {
public static final String TEXT_COLOR = "TEXT_COLOR";
private static SharedPreference prefs = ...
public static void setTextColor(int color) {
prefs.edit().putInt(TEXT_COLOR, color).apply();
}
public static int getTextColor() {
prefs.getInt(TEXT_COLOR, Color.WHITE);
}
}
```
KPrefs greatly simplifies it by using Kotlin's object pattern and delegates to achieve the following:
```Kotlin
object MyPrefs : KPref() {
var textColor: Int by kpref("TEXT_COLOR", Color.WHITE)
var bgColor: Int by kpref("BG_COLOR", Color.BLACK)
var isFirstLaunch: Boolean by kpref("IS_FIRST_LAUNCH", true)
...
}
```
By using `KPrefSample.textColor = Color.RED` or `textView.setTextColor(KPrefSample.textColor)` we can effectively set and save the value.
The values are retrieved lazily and are only done so once; future retrievals will be done with a local value, and updating a preference will both save it in the SharedPreference and update it locally.
The object inherits the initializer method `fun initialize(c: Context, preferenceName: String)`, which must be invoked (preferably in the Application class) before using a preference.
There is also a `reset()` method to clear the local values and have them retrieve from the SharedPreference again
## KPref Items
KAU supports Preferences that are created without xmls and through AppCompat.
The items are backed by a [FastAdapter](https://github.com/mikepenz/FastAdapter) and support [iicons](https://github.com/mikepenz/Android-Iconics)
The easiest way to create the settings is to extend `KPrefActivity`.
We will then override `onCreateKPrefs` to generate our adapter builder.
The adapter builder can easily add items using defined functions.
Each item added extends one or more contracts to configure it.
The contracts are as follows:
Contract | Mandatory | Optional | Description
:--- | :--- | :--- | :---
`CoreAttributeContract` | `NA` | `textColor` `accentColor` | Defines stylings that are added in every item
`CoreContract` | `titleRes` | `descRes` `iicon` | Implemented by every item
`BaseContract` | `getter` `setter` | `enabler` `onClick` `onDisabledClick` | Implemented by every preference item
`KPrefColorContract` | `NA` | `showPreview` | Additional configurations for the color picker
`KPrefTextContract` | `NA` | `textGetter` | Additional configurations for the text item
`KPrefSubItemsContract` | `itemBuilder` | `NA` | Contains a new list for the adapter to load when clicked
The kpref items are as followed:
Item | Implements | Description
:--- | :--- | :---
`checkbox` | `CoreContract` `BaseContract` | Checkbox item; by default, clicking it will toggle the checkbox and the kpref
`colorPicker` | `CoreContract` `BaseContract` `KPrefColorContract` | Color picker item; by default, clicking it will open a dialog which will change the color (int)
`header` | `CoreContract` | Header; just a title that isn't clickable
`text` | `CoreContract` `BaseContract` `KPrefTextContract` | Text item; displays the kpref as a String on the right; does not have click implementation by default
`plainText` | `BaseContract` | Plain text item; like `text` but does not deal with any preferences directly, so it doesn't need a getter or setter
This can be used to display text or deal with preference that are completely handed within the click event (eg a dialog).
`subItems` | `CoreContract` `KPrefSubItemsContract` | Sub items; contains a new page for the activity to load when clicked
An example of the adapter builder:
```kotlin
override fun onCreateKPrefs(savedInstanceState: android.os.Bundle?): KPrefAdapterBuilder.() -> Unit = {
textColor = { KPrefSample.textColor } // getter function so the new text color will be retrieved for every reload
accentColor = { KPrefSample.accentColor }
header(R.string.header)
/**
* This is how the setup looks like with all the proper tags
*/
checkbox(title = R.string.checkbox_1, getter = { KPrefSample.check1 }, setter = { KPrefSample.check1 = it },
builder = {
descRes = R.string.desc
})
/**
* This is how it looks like without the tags
*/
checkbox(R.string.checkbox_3, { KPrefSample.check3 }, { KPrefSample.check3 = it }) {
descRes = R.string.desc_dependent
enabler = { KPrefSample.check2 }
onDisabledClick = {
itemView, _, _ ->
itemView.context.toast("I am still disabled")
true
}
}
}
```
## Changelog XML
Create an xml resource with the following structure:
```xml