Awesome
Kyrie
Kyrie is a superset of Android's VectorDrawable
and AnimatedVectorDrawable
classes: it can do everything they can do and more.
Motivation
VectorDrawable
s are great because they provide density independence—they can be scaled arbitrarily on any device without loss of quality. AnimatedVectorDrawable
s make them even more awesome, allowing us to animate specific properties of a VectorDrawable
in a variety of ways.
However, these two classes have three main limitations:
- They can't be paused, resumed, or seeked.
- They can't be dynamically created at runtime (they must be inflated from a drawable resource).
- They only support a small subset of features that SVGs provide on the web.
Kyrie was created in order to address these problems.
Getting started
To create an animation using Kyrie, you first need to build a KyrieDrawable
. There are two ways to do this:
Option #1: from an existing VD/AVD resource
With Kyrie, you can convert an existing VectorDrawable
or AnimatedVectorDrawable
resource into a KyrieDrawable
with a single line:
val drawable = KyrieDrawable.create(context, R.drawable.my_vd_or_avd);
Option #2: programatically using a KyrieDrawable.Builder
You can also build KyrieDrawable
s at runtime using the builder pattern. KyrieDrawable
s are similar to SVGs and VectorDrawable
s in that they are tree-like structures built of Node
s. As you build the tree, you can optionally assign Animation
s to the properties of each Node
to create an animatable KyrieDrawable
.
Here is a snippet of code from the sample app that builds a material design circular progress indicator:
val drawable =
kyrieDrawable {
viewport = size(48f, 48f)
tint = Color.RED
group {
translateX(24f)
translateY(24f)
rotation(
Animation.ofFloat(0f, 720f)
.duration(4444)
.repeatCount(Animation.INFINITE)
)
path {
strokeColor(Color.WHITE)
strokeWidth(4f)
trimPathStart(
Animation.ofFloat(0f, 0.75f)
.duration(1333)
.repeatCount(Animation.INFINITE)
.interpolator("M 0 0 h .5 C .7 0 .6 1 1 1".asPathInterpolator())
)
trimPathEnd(
Animation.ofFloat(0.03f, 0.78f)
.duration(1333)
.repeatCount(Animation.INFINITE)
.interpolator("M 0 0 c .2 0 .1 1 .5 1 C 1 1 1 1 1 1".asPathInterpolator())
)
trimPathOffset(
Animation.ofFloat(0f, 0.25f)
.duration(1333)
.repeatCount(Animation.INFINITE)
)
strokeLineCap(StrokeLineCap.SQUARE)
pathData("M 0 -18 a 18 18 0 1 1 0 36 18 18 0 1 1 0 -36")
}
}
}
Features
Kyrie supports 100% of the features that VectorDrawable
s and AnimatedVectorDrawable
s provide. It also extends the functionality of VectorDrawable
s and AnimatedVectorDrawable
s in a number of ways, making it possible to create even more powerful and elaborate scalable assets and animations.
VectorDrawable
features
In addition to the features supported by VectorDrawable
, Kyrie provides the following:
<path>
features
CircleNode
. Equivalent to the<circle>
node in SVG.EllipseNode
. Equivalent to the<ellipse>
node in SVG.LineNode
. Equivalent to the<line>
node in SVG.RectangleNode
. Equivalent to the<rect>
node in SVG.strokeDashArray
(FloatArray
). Equivalent to thestroke-dasharray
attribute in SVG.strokeDashOffset
(Float
). Equivalent to thestroke-dashoffset
attribute in SVG.isScalingStroke
(Boolean
). Equivalent tovector-effect="non-scaling-stroke"
in SVG. Defines whether a path's stroke width will be affected by scaling transformations.- The
strokeMiterLimit
attribute is animatable.
<clip-path>
features
FillType
(eitherNON_ZERO
orEVEN_ODD
). Equivalent to theclip-rule
attribute in SVG.ClipType
(eitherINTERSECT
orDIFFERENCE
). Defines whether the clipping region is additive or subtractive.
<group>
features
- Transformations (
pivot
,scale
,rotation
, andtranslation
) can be set on anyNode
, not justGroupNode
s.
AnimatedVectorDrawable
features
In addition to the features supported by AnimatedVectorDrawable
, Kyrie provides the following:
setCurrentPlayTime(long)
.- Allows you to manually scrub the animation.
pause()
andresume()
.- Allows you to pause and resume the animation.
addListener(KyrieDrawable.Listener)
.- Allows you to listen for the following animation events: start, update, pause, resume, cancel, and end.
Further reading
- Check out this blog post for more on the motivation behind the library.
- Check out the sample app for example usages in both Java and Kotlin.
- Check out the documentation for a complete listing of all supported
Animation
s andNode
s that can be used when constructingKyrieDrawable
s programatically.
Dependency
Add this to your root build.gradle
file (not your module's build.gradle
file):
allprojects {
repositories {
// ...
jcenter()
}
}
Then add the library to your module's build.gradle
file:
dependencies {
// ...
implementation 'com.github.alexjlockwood:kyrie:0.2.1'
}
Compatibility
- Minimum Android SDK: Kyrie requires a minimum API level of 14.
- Compile Android SDK: Kyrie requires you to compile against API 28 or later.