aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 4143ca8a47e065f4ed154281d40ad53dd981f5e2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
**Note: v3.8.0 is the last release with support dependencies. Starting with 4.0.0-alpha01, androidx will be used**

---

<a href="https://allanwang.github.io/KAU/" target="_blank">
<img src="https://cdn.rawgit.com/AllanWang/KAU/master/files/images/logo.svg" alt="KAU" width="30%"/>
</a>

An extensive collection of <b>Kotlin Android Utils</b>

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.

<a href='https://play.google.com/store/apps/details?id=ca.allanwang.kau.sample&utm_source=github'><img alt='Get it on Google Play' width="30%" src='https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png'/></a>

[Changelog](docs/Changelog.md)
[Migration](docs/Migration.md)

------------

KAU is available on JitPack

[![](https://jitpack.io/v/ca.allanwang/kau.svg)](https://jitpack.io/#ca.allanwang/kau) 
[![Build Status](https://travis-ci.org/AllanWang/KAU.svg?branch=dev)](https://travis-ci.org/AllanWang/KAU)
[![Crowdin](https://d322cqt584bo4o.cloudfront.net/kotlin-android-utils/localized.svg)](https://crowdin.com/project/kotlin-android-utils)
[![Awesome Kotlin Badge](https://kotlin.link/awesome-kotlin.svg)](https://github.com/KotlinBy/awesome-kotlin)
[![ZenHub](https://img.shields.io/badge/Shipping%20faster%20with-ZenHub-45529A.svg)](https://app.zenhub.com/workspace/o/allanwang/kau/boards)
[![GitHub license](https://img.shields.io/badge/license-Apache%202-blue.svg)](https://raw.githubusercontent.com/AllanWang/KAU/master/LICENSE)

To apply, add the following to your root build.gradle:

```gradle
allprojects {
    repositories {
        ...
        jcenter()
        maven { url "https://jitpack.io" }
        google()
    }
}
```

(If you are using gradle < 4.0, use `maven { url "https://maven.google.com" }` instead of `google()`)

And add the following dependencies (You can use a specific version, commit, or -SNAPSHOT):

Note that only `core` is required if you want the basic features.
Note that if you use any particular submodule, it will automatically include all of its necessary dependencies.

```gradle
dependencies {
    // all submodules extend this
    implementation "ca.allanwang.kau:core:$KAU"
    // all submodules with extensive ui extend this
    implementation "ca.allanwang.kau:core-ui:$KAU"
    
    implementation "ca.allanwang.kau:about:$KAU"
    implementation "ca.allanwang.kau:colorpicker:$KAU"
    implementation "ca.allanwang.kau:kpref-activity:$KAU"
    implementation "ca.allanwang.kau:mediapicker:$KAU"
    implementation "ca.allanwang.kau:searchview:$KAU"
}

// optional buildscript plugin (see below)
buildscript {
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }

    dependencies {
        ...
        classpath "ca.allanwang:kau:${KAU}"
    }
}

```

(If you are using gradle < 4.0, use `compile` instead of `implementation`)

-----------

# Submodules 
> Linked to their respective docs.<br/>
> Included dependencies are only those with exposed APIs; see [new dependency configurations](https://developer.android.com/studio/build/gradle-plugin-3-0-0-migration.html#new_configurations).<br/>
> Implemented external dependencies are wrapped in parentheses.
> All KAU submodule dependencies are implemented, with the exception of `core` in `core-ui`.
This means that you'll need to explicitly include each submodule you'd like to use, even if another declared submodule depends on it.

## [Core](core#readme)
* Collection of extension functions and small helper methods applicable in almost any application.
* Notable features: 
  * [KPrefs](core#kprefs)
  * [Changelog XML](core#changelog-xml)
  * [FAQ XML](core#faq-xml)
  * [Kotterknife](core#kotterknife)
  * [Ripple Canvas](core#ripple-canvas)
  * [MeasureSpecDelegate](core#measure-spec-delegate)
  * [CollapsibleViewDelegate](core#collapsible-view-delegate)
  * [Swipe](core#swipe)
  * [Debounce](core#debounce)
  * [KAU Logger](core#kau-logger)
  * [Email Builder](core#email-builder)
  * [Extension Functions](core#extension-functions)
  * [Lazy Resettable](core#lazy-resettable)
* Includes 
[`AppCompat`](https://developer.android.com/topic/libraries/support-library/index.html), 
[`Material Dialogs (core)`](https://github.com/afollestad/material-dialogs),
[`Iconics`](https://github.com/mikepenz/Android-Iconics), 
[`Anko`](https://github.com/Kotlin/anko),
[`Kotlin stdlib`](https://kotlinlang.org/api/latest/jvm/stdlib/)

## [Core UI](core-ui#readme)
* Collection of complex views and widgets
* Includes `:core`, `:adapter`

## [About](about#readme)
* Modularized overlaying about section. Comes with a main panel, automatic lib detection, and a FAQ parser; also includes the lib strings for KAU.
* Includes `:core-ui`, `:adapter`, 
[`About Libraries`](https://github.com/mikepenz/AboutLibraries)

## [Adapter](adapter#readme)
* Kotlin bindings for the fast adapter, as well as modularized RecyclerView animations
* Includes `:core`, 
[`Fast Adapter`](https://github.com/mikepenz/FastAdapter)

## [Color Picker](colorpicker#readme)
* Implementation of a color picker dialog with subtle transitions and a decoupled callback
* Includes `:core`, 
([`Material Dialogs (commons)`](https://github.com/afollestad/material-dialogs))

## [KPref Activity](kpref-activity#readme)
* Fully programmatic implementation of a Preference Activity, backed by a RecyclerView
* Includes `:core`, `:adapter`, `:colorpicker`

## [Media Picker](mediapicker#readme)
* Fully functional image and video pickers, both as an overlay and as a requested activity.
* Includes `:core-ui`, 
[`Glide`](https://github.com/bumptech/glide),
([`Blurry`](https://github.com/wasabeef/Blurry))

## [SearchView](searchview#readme)
* Material searchview with kotlin bindings
* Includes `:core-ui`, `:adapter`

## [Gradle Plugin](buildSrc#readme)
* Gradle plugin to help facilitate versioning and other gradle functions

-----------

# Showcase

![About Activity Gif](https://raw.githubusercontent.com/AllanWang/Storage-Hub/master/kau/kau_about_activity.gif)
![Ink Indicator Gif](https://raw.githubusercontent.com/AllanWang/Storage-Hub/master/kau/kau_ink_indicator.gif)
![Color Picker Gif](https://raw.githubusercontent.com/AllanWang/Storage-Hub/master/kau/kau_color_picker.gif)
![Color Picker Custom Gif](https://raw.githubusercontent.com/AllanWang/Storage-Hub/master/kau/kau_color_picker_custom.gif)
![KPref Items Gif](https://raw.githubusercontent.com/AllanWang/Storage-Hub/master/kau/kau_kpref_items.gif)
![SearchView Gif](https://raw.githubusercontent.com/AllanWang/Storage-Hub/master/kau/kau_search_view.gif)
![Swipe Gif](https://raw.githubusercontent.com/AllanWang/Storage-Hub/master/kau/kau_swipe.gif)

# Proguard/MultiDex

Given that the core module contains a lot of extension functions, you may run into a dex error (over 64k methods)

To resolve that, add `multiDexEnabled true` under your `app.gradle > android > defaultConfig`

Likewise, it is highly recommended to use proguard to clean up your project upon release.
All KAU components support proguard out of the box. 
Some may have extra requirements for certain features, which will be detailed in their respective README.

## Translations

KAU depends on translations crowdsourced by the general public.
If you would like to contribute, please visit [here](https://crwd.in/kotlin-android-utils)

Special thanks to the following awesome people for translating significant portions of KAU!

| Language | Contributors |
|----------|--------------|
| Chinese (Simplified) | |
| French | [Vincent Kulak](https://github.com/VonOx) &bull; [Jean-Philippe Gravel](https://crowdin.com/profile/wokija) |
| Galician | [Xesús M. Mosquera](https://twitter.com/xesusmmc?lang=en) |
| German | [Bushido1992](https://forum.xda-developers.com/member.php?u=5179246) &bull; [Marcel Soehnchen](https://crowdin.com/profile/msoehnchen) &bull; [3LD0mi HA](https://forum.xda-developers.com/member.php?u=5860523) |
| Indonesian | [M. Angga Ariska](https://www.youtube.com/channel/UCkqMw81s2aw7bYO-U2YhD7w) |
| Italian | [Bonnee](https://github.com/Bonnee) |
| Korean | [잇스테이크](https://crowdin.com/profile/bexco2010) |
| Norwegian | |
| Polish | |
| Portuguese | [TheusKhan](https://crowdin.com/profile/TheusKhan) |
| Spanish | [Jahir Fiquitiva](https://jahirfiquitiva.me/) &bull; [Nefi Salazar](https://plus.google.com/u/0/105547968033551087431)|
| Thai | |
| Turkish | |
| Vietnamese | [Alienz](https://crowdin.com/profile/alienyd) |

The full activity stream for the translations can be found [here](https://crowdin.com/project/kotlin-android-utils/activity_stream)