Swipe Action View
SwipeActionView is a swipe-able view, which allows users to perform actions by swiping it to the left or right side.
Table of contents
- Preview
- Installation
- Quick Example
- Sample
- The idea
- Gesture listener
- Disabling gestures
- Ripple animations
- Click listeners
- Animate from code
- Activation distance
- Attributes
- Animations
- Credits
- License
Preview
Installation
Add the JitPack repository to your root build.gradle:
allprojects {
repositories {
maven { url "https://jitpack.io" }
}
}And add the dependency in your module's build.gradle:
dependencies {
implementation 'com.github.Tunous:SwipeActionView:VERSION_HERE'
}Replace VERISION_HERE with the version you want to use. See the tags on the top of this file to see the latest available version.
Quick example
Adding SwipeActionView to your projects requires only adding it to XML and setting up SwipeGestureListener.
Below example will create TextView that can be swiped both to the left or right side with two icons behind.
<me.thanel.swipeactionview.SwipeActionView
android:id="@+id/swipe_view"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="?colorPrimary">
<ImageView
android:layout_width="24dp"
android:layout_height="24dp"
android:src="@mipmap/ic_launcher"/>
<ImageView
android:layout_width="24dp"
android:layout_height="24dp"
android:layout_gravity="end"
android:src="@mipmap/ic_launcher"/>
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@android:color/background_light"
android:padding="16dp"
android:text="Swipe me"/>
</me.thanel.swipeactionview.SwipeActionView>SwipeActionView swipeView = findViewById(R.id.swipe_view);
swipeView.setSwipeGestureListener(new SwipeGestureListener() {
@Override
public boolean onSwipedLeft(@NonNull SwipeActionView swipeActionView) {
showToast("Swiped left");
return true;
}
@Override
public boolean onSwipedRight(@NonNull SwipeActionView swipeActionView) {
showToast("Swiped right");
return true;
}
});Sample
For an example implementation of SwipeActionView see the included sample project.
You can manually compile the apk using source code or download from the releases page of this repository.
The idea
The main idea behind this library is a concept of container and background views. It allows for complete control over the look of the created views.
In the quick example section you can see that the SwipeActionView has three child views. The first two are background views, and the last one is the container. To create working version of SwipeActionView, you are only required to specify single background view and container. Second background view can be added when you want to be able to swipe in both directions.
Container
The container is a view which is drawn above other views. In the default state, this is the only visible view, and it is what gets moved when users perform swipe gestures. It can be either a simple TextView, custom view or even some sort of view group like LinearLayout. There is no limit for that, which allows you to gain complete control over the look of your views.
Background views
Background views are the mostly invisible part of SwipeActionView. They get revealed only when users start performing swipe gestures. (Unless your container view has transparent background)
You can specify for which swipe direction each of them corresponds by setting their layout_gravity attribute.
Default value or setting it to either left and/or start means that it will start appearing when users perform right swipe gesture. On the other hand setting it to end and/or right will result in the view to start appearing when users swipe to the left. This doesn't mean that you aren't allowed to use other layout_gravity options like center. They will still control the view as usual and will be ignored by SwipeActionView.
This behavior allows you to add single background and by specifying its layout_gravity determine whether SwipeActionView should be possible to be swiped only to the left or right side.
Note: There can be only one view for each direction. This means that if one of them is placed on the left side, the second one must be put on the right side to avoid errors.
Example
<me.thanel.swipeactionview.SwipeActionView
android:id="@+id/swipe_view"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="?colorPrimary">
<!-- First background view.
It will be located on left side of the view and will allow users to perform
right swipe gesture. -->
<ImageView
android:layout_width="24dp"
android:layout_height="24dp"
android:src="@mipmap/ic_launcher"/>
<!-- Second background view.
This one will be located on the right side and allow users to perform
left swipe gesture as its layout_gravity is changed to "end". -->
<ImageView
android:layout_width="24dp"
android:layout_height="24dp"
android:layout_gravity="end"
android:src="@mipmap/ic_launcher"/>
<!-- Container.
This is what users will see when the view is not being swiped. -->
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@android:color/background_light"
android:padding="16dp"
android:text="Swipe me"/>
</me.thanel.swipeactionview.SwipeActionView>Gesture listener
In order to be able to perform actions when users swipe the SwipeActionView you have to setup the listener with the setSwipeGestureListener(SwipeGestureListener) method. It takes SwipeGestureListener as a parameter.
SwipeGestureListener consists of two methods. One for performing an action when the view is swiped to the left and one when it is swiped to the right side.
Each of these methods returns Boolean as a result. Most of the time you'll want to return true here. Returning false is designed for advanced usage. By doing so, the view won't be automatically animated to the original position but will stay at the full translation. This allows you to manipulate the content of the visible background view. One great example of this is displaying progress wheel and manually returning the view to the original position once some long action finishes execution.
To return the view to its original position you can call the animateToOriginalPosition() method at any time.
swipeView.setSwipeGestureListener(new SwipeGestureListener() {
@Override
public boolean onSwipedLeft(@NonNull SwipeActionView swipeActionView) {
showToast("Swiped left");
// Returning true automatically moves view to original position
return true;
}
@Override
public boolean onSwipedRight(@NonNull SwipeActionView swipeActionView) {
showToast("Swiped right");
// Returning false requires calling animateToOriginalPosition() manually to
// reset view to original position
// Here we are using optional parameter which will move our view to
// original position after delay in ms. In this case it's 2s.
swipeActionView.animateToOriginalPosition(2000);
return false;
}
});Disabling gestures
If you want to dynamically enable or disable gesture in a specific direction you can use the setDirectionEnabled(SwipeDirection, Boolean) method.
Note: The gesture enabling part is controlled by presence and visibility of background views. This method is only provided for convenience since it can also be changed by switching visibility of background views. It was coded like this so the specific swipe directions can be disabled by default from XML using visibility attribute on views corresponding to these directions.
swipeView.setDirectionEnabled(SwipeDirection.Left, false);Ripple animations
SwipeActionView comes with optional support for displaying ripple animations when gestures are performed. All you have to do to enable them is to give them a color from XML or code. To do so from the code, you can use the setRippleColor(SwipeDirection, Int) method.
To disable ripple animations you can enter -1 as value for color.
swipeView.setRippleColor(SwipeDirection.Right, Color.BLUE);Click listeners
SwipeActionView makes sure that any click listeners will work correctly. You can use setClickListener(View.OnClickListener) as usual and they should work, including views located in the container.
The only exception is that you shouldn't add click listeners for background views. This library wasn't designed to add support for this behavior. If it's possible then, that's only a positive side effect. You are better of with using libraries such as AndroidSwipeLayout instead.
Animate from code
When needed you can manually animate the view to desired position from code by using one of the dedicated methods.
Method animateInDirection(swipeDirection: SwipeDirection, animateBack: Boolean, delayBeforeAnimatingBack: Long) animates the view in the specified direction and optionally animates it back after a delay.
// Animate the view to the right and then animate it back after 1s
swipeView.animateInDirection(SwipeDirection.Right, true, 1000);
// Animate the view to the left and do not animate it back
swipeView.animateInDirection(SwipeDirection.Left, false);Method animateToOriginalPosition(startDelay: Long) animates the view to its original position with optional start delay.
// Wait 500ms and then animate the view to its original position
swipeView.animateToOriginalPosition(500)
// Instantly animate the view to its original position
swipeView.animateToOriginalPosition()Activation distance
You can customize the siwpe distance required for callbacks to be executed by using the activationDistanceRatio property. It receives a value in range from 0.0f to 1.0f, which means the percentage of background view that has to be revealed. For example if set to 0.5f the user has to reveal at least half of the background view before releasing their finger in order for the gesture callbacks to be executed.
Attributes
app:sav_rippleTakesPadding="true|false"
If you want ripple effect to take padding together with container view you can set this attribute to true.
app:sav_swipeLeftRippleColor="@color"
Sets color for ripple displayed when users swipe left.
app:sav_swipeRightRippleColor="@color"
Sets color for ripple displayed when users swipe right.
Tools attributes
SwipeActionView has special attributes used only in the editor mode. They make it possible to preview ripples or contents of background views without worrying about side effects. They are entirely ignored when running on the device.
app:sav_tools_previewBackground="swipeLeft|swipeRight"
Shows background view for swipe left or right gesture.
app:sav_tools_previewRipple="swipeLeft|swipeRight"
Shows ripple for swipe left or right gesture.
Animations
SwipeActionView also comes with support for custom animations. There are two listeners that you can set in your code. They will be called with current swipe progress while users perform swipe gesture.
By default, there is only one animator included which scales the background views. You can use it as an example of how to implement custom animations or use it directly if it's good enough for you.
Credits
This library wouldn't be created without help and work of Brian Robles.
His KarmaMachine Reddit application was my direct inspiration when I was creating it for my application.
He also created SwipeRippleDrawable and allowed me to reimplement it for purposes of this library.
Huge thanks!
License
Copyright © 2016-2019 Łukasz Rutkowski
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.