What is it?
Spruce is a lightweight animation library that helps choreograph the animations on the screen. With so many different animation libraries out there, developers need to make sure that each view is animating at the appropriate time. Spruce can help designers request complex multi-view animations and not have the developers cringe at the prototype.
Gradle
Add the following to your project's root build.gradle file
repositories {
maven {
url "https://dl.bintray.com/bfears/maven"
}
}Add the following to your project's build.gradle file
dependencies {
implementation 'com.willowtreeapps.spruce:spruce-android:1.1.0'
Basic Usage
Animator spruceAnimator = new Spruce
.SpruceBuilder(parentViewGroup)
.sortWith(new Default(/*interObjectDelay=*/50L))
.animateWith(new Animator[] {DefaultAnimations.shrinkAnimator(parentViewGroup, /*duration=*/800)})
.start();Preparing for Animation
Spruce comes packed with Animator options within the DefaultAnimations class meant to make your life easier when calling an animation. Let's say we want to have your views fade in. For example, we would create an animators = new Animator[] {} and add DefaultAnimations.fadeInAnimator(parentViewGroup, /*duration=*/800) as an array item. If you want a view to fade in, then you need to make sure that it is already faded out. To do that, we need to set the alpha to 0 on the views or you could first use a fade out animator.
Running the Animation
Use the following command to run a basic animation on your view.
Animator spruceAnimator = new Spruce
.SpruceBuilder(parentViewGroup)
.sortWith(new DefaultSort(/*interObjectDelay=*/50L))
.animateWith(animators)
.start();Using a SortFunction
Luckily, Spruce comes with 8 SortFunction implementations with a wide open possibility to make more! Use the SortFunction to change the order in which views animate. Consider the following example:
LinearSort sort = new LinearSort(/*interObjectDelay=*/100L, /*reversed=*/false, LinearSort.Direction.TOP_TO_BOTTOM);In this example we have created a LinearSort which will have views animate in from the top to bottom. We can change the look and feel of the animation by using a RadialSort instead which will have the views animate in a circular fashion. If we wanted to use this sort in an actual Spruce start() call then that would look something like:
Animator spruceAnimator = new Spruce
.SpruceBuilder(parentViewGroup)
.sortWith(new LinearSort(/*interObjectDelay=*/100L, /*reversed=*/false, LinearSort.Direction.TOP_TO_BOTTOM))
.animateWith(DefaultAnimations.shrinkAnimator(parentViewGroup, /*duration=*/800))
.start();Definitely play around with the stock SortFunction implementations until you find the one that is perfect for you! Check out the example app if you want to get previews of what each SortFunction will look like.
The Animators
The animations used in Spruce are produced by leveraging the Animator class. You may provide your own custom animations by creating your own Animator and provide it to the as part of an Animator[] to SpruceBuilder.animateWith(Animator... animators). For more information on using the Animator .
Standard Animation
The DefaultAnimation class provides simple Animator methods to apply the change Animator to the views. Use this class if you want to have a stock linear movement of the changes.
Sort Functions
With all different types of animations, especially those dealing with subviews, we have to consider a way in which we want to animate them. Some views can have 0 subviews while others may have hundreds. To handle this, we have the notion of a SortFunction. What this will do is take each of the subviews in the ViewGroup, and apply a mapping from the specific subview to the exact delay that it should wait before animating. Some of these will sort in a radial formation while others may actually sort randomly. One of the cool features of Spruce, is that you can actually define your own SortFunction and then the animation will look completely different. Luckily, Spruce also comes jam packed with a ton of default SortFunction classes to make everything easier on you as the developer. Take a look at some of the default SortFunction classes we have and see if you can use them or branch off of them for your cool and custom animations!
The SortFunction Interface
A very simple interface that requires classes to extend the following class
public abstract class SortFunction {
public abstract List<SpruceTimedView> getViewListWithTimeOffsets(ViewGroup parent, List<View> children);
}What the above class needs to do is take in a ViewGroup parent and a List of View children or subviews to generate a list of subviews and their animation offsets. Once the list of subviews has been generated, you can define your own sort metric to determine in which order the View's should animate. To do so, you need to create a List of SpruceTimedView's. This special class has two properties: (1) View view and (2) long timeOffset. Your SortFunction can define the timeOffset however it likes, but the animators will use this to determine how long it should delay the start of that specific view from animating. The best way to learn, is to play around. So why not have some fun and make your own SortFunction!
About Sort Functions
To make sure that developers can use Spruce out of the box, we included about 8 stock SortFunction implementations. These are some of the main functions we use at WillowTree and are so excited to see what others come up with!
DefaultSortLinearSortCorneredSortRadialSortRandomSortInlineSortContinousSortContinuousWeightedSort
Check out the docs here for more information
View Exclusion Feature
Spruce Animate all the views inside the view group. One of the key tips for pulling the best performance out of an Android app is to maintain a flat hierarchy. Spruce is now Introducing a new Exclusion feature.
This work in 2 modes:
- NORMAL_MODE: This mode should be used when you have view groups like Constraint/Frame/Relative/Linear Layouts. We feed a list of ids to be excluded to the SpruceBuilder.
- R_L_MODE: This mode is used when we have ListView/RecyclerView. The only difference with the first mode is that we pass in the positions to be excluded instead of Ids.
Animator spruceAnimator = new Spruce
.SpruceBuilder(parentViewGroup)
.sortWith(new LinearSort(/*interObjectDelay=*/100L, /*reversed=*/false, LinearSort.Direction.TOP_TO_BOTTOM))
.excludeViews(getExcludedViewIds(), NORMAL_MODE)
//or
.excludeViews(getExcludedViewPosition(), R_L_MODE)
.start();Sort Function Interpolators
Spruce now allows the user to control the overall flow of sort function using Interpolators.
Animator spruceAnimator = new Spruce
.SpruceBuilder(parentViewGroup)
.sortWith(new LinearSort(/*interObjectDelay=*/100L, /*reversed=*/false, LinearSort.Direction.TOP_TO_BOTTOM))
.addInterpolator(new LinearInterpolator())
.start();
