Anko is a library which makes Android application development faster and easier. It makes your code clean and easy to read, and lets you forget about rough edges of Android SDK for Java.
Just a brief example. Here is a "hello world" written with Anko:
verticalLayout {
val name = editText()
button("Say Hello") {
onClick { toast("Hello, ${name.text}!") }
}
}Code above creates a button inside a LinearLayout and attaches an OnClickListener to that button.
As you might have guessed, it's a DSL for Android. It is written in Kotlin.
By default, UI in Android is written using XML. That is inconvenient in the following ways:
- It is not typesafe
- It is not null-safe
- It forces you to write almost the same code for every layout you make
- XML is parsed on the device wasting CPU time and battery
- Most of all, it allows no code reuse.
While you can create UI programmatically, it's hardly done because it's somewhat ugly and hard to maintain. Here's a plain Kotlin version (one in Java is even longer):
val act = this
val layout = LinearLayout(act)
layout.orientation = LinearLayout.VERTICAL
val name = EditText(act)
val button = Button(act)
button.text = "Say Hello"
button.setOnClickListener {
Toast.makeText(act, "Hello, ${name.text}!", Toast.LENGTH_SHORT).show()
}
layout.addView(name)
layout.addView(button)A DSL makes the same logic easy to read, easy to write and there is no runtime overhead. Here it is again:
verticalLayout {
val name = editText()
button("Say Hello") {
onClick { toast("Hello, ${name.text}!") }
}
}You don't have to rewrite all your UI with Anko. You can keep your old classes written in Java. Moreover, if you still want (or have) to write a Kotlin activity class and inflate an XML layout for some reason, you can use View properties, which would make things easier:
// Same as findViewById(), simpler to use
val name = find<TextView>(R.id.name)
name.hint = "Enter your name"
name.onClick { /*do something*/ }You can make your code even more compact by using Kotlin Android Extensions.
There is no 🎩. Anko consists of some Kotlin extension functions and properties arranged into type-safe builders, as described under Type Safe Builders.
Since it's somewhat tedious to write all these extensions by hand, they're generated automatically using android.jar files from Android SDK as sources.
Short answer: yes.
For example, you might want to use a MapView in the DSL. Then just write this in any Kotlin file from where you could import it:
public inline fun ViewManager.mapView(theme: Int = 0) = mapView(theme) {}
public inline fun ViewManager.mapView(theme: Int = 0, init: MapView.() -> Unit) = ankoView({ MapView(it) }, theme, init){ MapView(it) } is a factory function for your custom View. It accepts a Context instance.
So now you can write this:
frameLayout {
val mapView = mapView().lparams(width = matchParent)
}Also see Extending Anko if you need to create top-level DSL views.
There's a template project showing how to include Anko library into your Android Gradle project.
Basically, all you have to do is to add an additional repository and a compile dependency:
dependencies {
compile 'org.jetbrains.anko:anko-sdk15:0.9' // sdk19, sdk21, sdk23 are also available
compile 'org.jetbrains.anko:anko-support-v4:0.9' // In case you need support-v4 bindings
compile 'org.jetbrains.anko:anko-appcompat-v7:0.9' // For appcompat-v7 bindings
}If your project is not based on Gradle, just attach jars from the releases page or from the jcenter repository as project library dependencies and that's it.
If you don't need the DSL features of Anko, you can just reference org.jetbrains.anko:anko-common, and that's all you have to do.
If you need the DSL features of Anko, you need to reference different libraries.
First, you need to reference a main library based on which minSdkVersion you target.
anko-common is referenced by those libraries, so you don't need to specify it yourself.
Here are the available libraries:
org.jetbrains.anko:anko-sdk15for 15 <=minSdkVersion< 19org.jetbrains.anko:anko-sdk19for 19 <=minSdkVersion< 21org.jetbrains.anko:anko-sdk21for 21 <=minSdkVersion< 23org.jetbrains.anko:anko-sdk23for 23 <=minSdkVersion
Then, for any Android Support library you referenced in your build.gradle, you need to add the matching Anko library, if you want some more Anko magic for those specific Android Support libraries. Here are all available Anko Android Support libraries:
org.jetbrains.anko:anko-support-v4org.jetbrains.anko:anko-appcompat-v7org.jetbrains.anko:anko-cardview-v7org.jetbrains.anko:anko-gridlayout-v7org.jetbrains.anko:anko-recyclerview-v7org.jetbrains.anko:anko-designorg.jetbrains.anko:anko-percent
Here is an example:
android {
...
defaultConfig {
...
minSdkVersion 15 // Min SDK version is 15 in this example
targetSdkVersion 23
...
}
...
}
dependencies {
...
// Note the used support libs
compile 'com.android.support:appcompat-v7:23.1.1'
compile 'com.android.support:design:23.1.1'
compile 'com.android.support:recyclerview-v7:23.1.1'
compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin-version"
compile "org.jetbrains.anko:anko-sdk15:$anko-version" // So here it's 15 too
// Anko libs matching support libs
compile "org.jetbrains.anko:anko-appcompat-v7:$anko-version"
compile "org.jetbrains.anko:anko-design:$anko-version"
compile "org.jetbrains.anko:anko-recyclerview-v7:$anko-version"
}Instructions for building Anko are located under Building.
As mentioned above, Anko is written in Kotlin. In case you are not familiar with Kotlin, please refer to kotlinlang.org. Kotlin is similar enough to Java, so learning it will be easy.
In Anko, you don't need to inherit from any special classes: just use standard Activity, Fragment, FragmentActivity or whatever you want.
First of all, import org.jetbrains.anko.* to use Anko DSL in your classes.
DSL is available in onCreate():
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
verticalLayout {
padding = dip(30)
editText {
hint = "Name"
textSize = 24f
}
editText {
hint = "Password"
textSize = 24f
}
button("Login") {
textSize = 26f
}
}
}| 🐧 |
There's no explicit call to setContentView(R.layout.something): Anko sets content views automatically for Activities (and only for them).
|
hint and textSize are synthetic extension properties bound to JavaBean-style getters and setters, padding is an extension property from Anko. Either of these exists for most View properties allowing
you to write text = "Some text" instead of setText("Some text").
verticalLayout (a LinearLayout but already with a LinearLayout.VERTICAL orientation), editText and button are
extension functions. Such functions also exist for almost every View in Android
framework, and they work in Activities, Fragments (both default and that from android.support package) and even for Context.
If you have a Context instance, you can write DSL constructs like this:
val name: EditText = with(myContext) {
editText {
hint = "Name"
}
}Although you can use the DSL directly (in onCreate() or everywhere else), without creating any extra classes, it is often convenient to have UI in the separate class. If you use the provided AnkoComponent interface, you also you get a DSL layout preview feature for free.
class MyActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
super.onCreate(savedInstanceState, persistentState)
MyActivityUI().setContentView(this)
}
}
class MyActivityUI : AnkoComponent<MyActivity> {
override fun createView(ui: AnkoContext<MyActivity>) = with(ui) {
verticalLayout {
val name = editText()
button("Say Hello") {
onClick { ctx.toast("Hello, ${name.text}!") }
}
}
}
}As you probably noticed earlier, the button() function in the previous section accepts a String parameter. Such helper methods exist for some views such
as TextView, EditText, Button or ImageView.
If you don't need to set any properties for some particular View, you can omit {} and write button("Ok") or even just button():
verticalLayout {
button("Ok")
button("Cancel")
}Positioning of widgets inside parent containers can be tuned using LayoutParams. In XML it looks like this:
<ImageView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_marginLeft="5dip"
android:layout_marginTop="10dip"
android:src="@drawable/something" />In Anko, you specify LayoutParams right after a View description using lparams():
linearLayout {
button("Login") {
textSize = 26f
}.lparams(width = wrapContent) {
horizontalMargin = dip(5)
topMargin = dip(10)
}
}If you specify lparams(), but omit width and/or height, their default values are both WRAP_CONTENT. But you always can pass them explicitly: use named arguments.
Some convenient helper properties to notice:
horizontalMarginsets both left and right margins,verticalMarginset top and bottom ones, andmarginsets all four margins simultaneously.
Note that lparams() are different for different layouts, for example, in the case of RelativeLayout:
val ID_OK = 1
relativeLayout {
button("Ok") {
id = ID_OK
}.lparams { alignParentTop() }
button("Cancel").lparams { below(ID_OK) }
}You can set listeners from Anko code:
button("Login") {
onClick {
login(name, password)
}
}It would be the same as this:
button.setOnClickListener(object : OnClickListener {
override fun onClick(v: View) {
login(name, password)
}
})Anko is very helpful when you have listeners with lots of methods. Consider the following code written without using Anko:
seekBar.setOnSeekBarChangeListener(object: OnSeekBarChangeListener {
override fun onProgressChanged(seekBar: SeekBar, progress: Int, fromUser: Boolean) {
// Something
}
override fun onStartTrackingTouch(seekBar: SeekBar?) {
// Just an empty method
}
override fun onStopTrackingTouch(seekBar: SeekBar) {
// Another empty method
}
})And now with Anko:
seekBar {
onSeekBarChangeListener {
onProgressChanged { seekBar, progress, fromUser ->
// Something
}
}
}If you set onProgressChanged() and onStartTrackingTouch() for the same View, these two "partially defined" listeners will be merged. For the same listener method, last wins.
All examples in the previous chapters used raw Java strings, but it is hardly a good practice. Typically you put all your string data into res/values/ directory and access it at runtime calling, for example, getString(R.string.login).
Fortunately, in Anko you can pass resource identifiers both to helper methods (button(R.string.login)) and to extension properties (button { textResource = R.string.login }).
Note that the property name is not the same: instead of text, hint, image, we now use textResource, hintResource and imageResource.
| 🐧 |
Resource properties always throw AnkoException when read.
|
Two simple extension functions to make the code more readable.
| Function | Result |
|---|---|
0xff0000.opaque |
non-transparent red |
0x99.gray.opaque |
non-transparent #999999 gray |
You can specify dimension values in dip (density-independent pixels) or in sp (scale-independent pixels): dip(dipValue) or sp(spValue). Note that the textSize
property already accepts sp (textSize = 16f). Use px2dip and px2sp to convert backwards.
Sometimes you need to pass a Context instance to some Android SDK method from your Activity code.
Usually you can just use this, but what if you're inside the inner class? You would probably write SomeActivity.this in case of Java
and this@SomeActivity if you're writing in Kotlin.
With Anko you can just write ctx. It is an extension property which works both inside Activity and Service and is even
accessible from Fragment (it uses getActivity() method under the hood). You can also get an Activity instance using act extension property.
Before the Beginning of Time Anko always used UI tag as a top-level DSL element:
UI {
editText {
hint = "Name"
}
}You can still use this tag if you want. And it would be much easier to extend DSL as you have to declare only one ViewManager.customView function.
See Extending Anko for more information.
It is easy to insert an XML layout into DSL. Use the include() function:
include<View>(R.layout.something) {
backgroundColor = Color.RED
}.lparams(width = matchParent) { margin = dip(12) }You can use lparams() as usual, and if you provide a specific type instead of View, you can also use this type inside {}:
include<TextView>(R.layout.textfield) {
text = "Hello, world!"
}Anko supports styling: style() is simply a function that accepts View, is applied for the View itself, and then recursively to each child of a View if it is a ViewGroup:
verticalLayout {
editText {
hint = "Name"
}
editText {
hint = "Password"
}
}.style { view -> when(view) {
is EditText -> view.textSize = 20f
}}