Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tunous/swipeactionview
Android swipe-able view, which allows users to perform actions with swipe gestures.
https://github.com/tunous/swipeactionview
android android-library android-ui swipe-gestures
Last synced: 8 days ago
JSON representation
Android swipe-able view, which allows users to perform actions with swipe gestures.
- Host: GitHub
- URL: https://github.com/tunous/swipeactionview
- Owner: Tunous
- License: apache-2.0
- Created: 2016-08-18T19:07:04.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-02-25T14:02:24.000Z (9 months ago)
- Last Synced: 2024-10-23T01:38:30.439Z (16 days ago)
- Topics: android, android-library, android-ui, swipe-gestures
- Language: Kotlin
- Homepage:
- Size: 1.08 MB
- Stars: 198
- Watchers: 9
- Forks: 17
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Swipe Action View
[](https://travis-ci.org/Tunous/SwipeActionView)
[](https://jitpack.io/#Tunous/SwipeActionView)
[](https://android-arsenal.com/details/1/5250)
[](https://android-arsenal.com/api?level=14)
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](#preview)
- [Installation](#installation)
- [Quick Example](#quick-example)
- [Sample](#sample)
- [The idea](#idea)
- [Container](#container)
- [Background views](#bg-views)
- [Gesture listener](#gesture-listener)
- [Disabling gestures](#disabling-gestures)
- [Ripple animations](#ripple-animations)
- [Click listeners](#click-listeners)
- [Animate from code](#code-animation)
- [Activation distance](#activation-distance)
- [Attributes](#attr)
- [sav_rippleTakesPadding](#attr-rippleTakesPadding)
- [sav_swipeLeftRippleColor](#attr-swipeLeftRippleColor)
- [sav_swipeRightRippleColor](#attr-swipeRightRippleColor)
- [Tools attributes](#attr-tools)
- [sav_tools_previewBackground](#attr-tools-previewBackground)
- [sav_tools_previewRipple](#attr-tools-previewRipple)
- [Animations](#animations)
- [Credits](#credits)
- [License](#license)
# Preview
Add the JitPack repository to your root `build.gradle`:
```groovy
allprojects {
repositories {
maven { url "https://jitpack.io" }
}
}
```
And add the dependency in your module's `build.gradle`:
```groovy
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.*
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.
```xml
```
```java
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](#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
```xml
```
# 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.
```java
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.
```java
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.
```java
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.
```java
// 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.
```java
// 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.
#### `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][SwipeRippleDrawable] 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.
```
[sample]: https://github.com/Tunous/SwipeActionView/tree/master/sample
[releases page]: https://github.com/Tunous/SwipeActionView/releases
[container]: #container
[background views]: #bg-views
[AndroidSwipeLayout]: https://github.com/daimajia/AndroidSwipeLayout
[Brian Robles]: https://github.com/brianrobles204
[KarmaMachine]: https://play.google.com/store/apps/details?id=com.brianrobles204.karmamachine
[SwipeRippleDrawable]: https://github.com/Tunous/SwipeActionView/blob/master/library/src/main/kotlin/me/thanel/swipeactionview/SwipeRippleDrawable.kt