# android-gif-drawable
**Repository Path**: hyperions/android-gif-drawable
## Basic Information
- **Project Name**: android-gif-drawable
- **Description**: Views and Drawable for displaying animated GIFs on Android
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-04-22
- **Last Updated**: 2024-06-09
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
android-gif-drawable
====================
[](https://maven-badges.herokuapp.com/maven-central/pl.droidsonroids.gif/android-gif-drawable)
[](https://www.bitrise.io/app/78fd40a5596e97e7)
[](https://android-arsenal.com/details/1/1147)
[](http://android-libs.com/lib/android-gif-drawable)
[](http://androidweekly.net/issues/issue-93)
[](https://android-arsenal.com/api?level=9)
[](http://www.javadoc.io/doc/pl.droidsonroids.gif/android-gif-drawable)
`View`s and `Drawable` for animated GIFs in Android.
## Overview
Bundled GIFLib via JNI is used to render frames. This way should be more efficient than `WebView` or `Movie` classes.
### [Javadoc](http://www.javadoc.io/doc/pl.droidsonroids.gif/android-gif-drawable)
### Setup
#### Gradle (Android Studio)
Insert the following dependency to `build.gradle` file of your project.
```groovy
dependencies {
compile 'pl.droidsonroids.gif:android-gif-drawable:1.2.8'
}
```
Note that Maven central repository should be defined eg. in top-level `build.gradle` like this:
```groovy
buildscript {
repositories {
mavenCentral()
}
}
allprojects {
repositories {
mavenCentral()
}
}
```
#### Gradle, snapshot repository
Current development builds (build from `dev` branch) are published to OSS snapshot repository. To use them, specify repository URL in `repositories` block:
```groovy
repositories {
mavenCentral()
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
}
dependencies {
compile 'pl.droidsonroids.gif:android-gif-drawable:1.2.+'
}
```
#### Maven dependency
```xml
pl.droidsonroids.gif
android-gif-drawable
insert latest version here
aar
```
#### Eclipse
See [Sample eclipse project](https://github.com/koral--/android-gif-drawable-eclipse-sample) with setup instructions.
#### Download
**[Latest release downloads](https://github.com/koral--/android-gif-drawable/releases/latest)**
### Requirements
+ Android 2.3+ (API level 9+)
+ for `GifTextureView` Android 4.0+ (API level 14+) and hardware-accelerated rendering
+ for `GifTexImage2D` OpenGL ES 2.0+
#### Building from source
+ [Android NDK](http://developer.android.com/tools/sdk/ndk/index.html) needed to compile native sources
## Usage
### Sample project
See `sample` directory. Sample project is under construction. Not all features are covered yet.
### From XML
The simplest way is to use `GifImageView` (or `GifImageButton`) like a normal `ImageView`:
```xml
```
If drawables declared by `android:src` and/or `android:background` are GIF files then they
will be automatically recognized as `GifDrawable`s and animated. If given drawable is not a GIF then
mentioned Views work like plain `ImageView` and `ImageButton`.
`GifTextView` allows you to use GIFs as compound drawables and background.
```xml
```
### From Java code
`GifImageView`, `GifImageButton` and `GifTextView` have also hooks for setters implemented. So animated GIFs can be set by calling `setImageResource(int resId)` and `setBackgroundResource(int resId)`
`GifDrawable` can be constructed directly from various sources:
```java
//asset file
GifDrawable gifFromAssets = new GifDrawable( getAssets(), "anim.gif" );
//resource (drawable or raw)
GifDrawable gifFromResource = new GifDrawable( getResources(), R.drawable.anim );
//Uri
ContentResolver contentResolver = ... //can be null for file:// Uris
GifDrawable gifFromUri = new GifDrawable( contentResolver, gifUri );
//byte array
byte[] rawGifBytes = ...
GifDrawable gifFromBytes = new GifDrawable( rawGifBytes );
//FileDescriptor
FileDescriptor fd = new RandomAccessFile( "/path/anim.gif", "r" ).getFD();
GifDrawable gifFromFd = new GifDrawable( fd );
//file path
GifDrawable gifFromPath = new GifDrawable( "/path/anim.gif" );
//file
File gifFile = new File(getFilesDir(),"anim.gif");
GifDrawable gifFromFile = new GifDrawable(gifFile);
//AssetFileDescriptor
AssetFileDescriptor afd = getAssets().openFd( "anim.gif" );
GifDrawable gifFromAfd = new GifDrawable( afd );
//InputStream (it must support marking)
InputStream sourceIs = ...
BufferedInputStream bis = new BufferedInputStream( sourceIs, GIF_LENGTH );
GifDrawable gifFromStream = new GifDrawable( bis );
//direct ByteBuffer
ByteBuffer rawGifBytes = ...
GifDrawable gifFromBytes = new GifDrawable( rawGifBytes );
````
InputStreams are closed automatically in finalizer if GifDrawable is no longer needed
so you don't need to explicitly close them. Calling `recycle()` will also close
underlying input source.
Note that all input sources need to have ability to rewind to the beginning. It is required to correctly play animated GIFs
(where animation is repeatable) since subsequent frames are decoded on demand from source.
#### Animation control
`GifDrawable` implements an `Animatable` and `MediaPlayerControl` so you can use its methods and more:
+ `stop()` - stops the animation, can be called from any thread
+ `start()` - starts the animation, can be called from any thread
+ `isRunning()` - returns whether animation is currently running or not
+ `reset()` - rewinds the animation, does not restart stopped one
+ `setSpeed(float factor)` - sets new animation speed factor, eg. passing 2.0f will double the animation speed
+ `seekTo(int position)` - seeks animation (within current loop) to given `position` (in milliseconds)
+ `getDuration()` - returns duration of one loop of the animation
+ `getCurrentPosition()` - returns elapsed time from the beginning of a current loop of animation
##### Using [MediaPlayerControl](http://developer.android.com/reference/android/widget/MediaController.MediaPlayerControl.html)
Standard controls for a MediaPlayer (like in [VideoView](http://developer.android.com/reference/android/widget/VideoView.html)) can be used to control GIF animation and show its current progress.
Just set `GifDrawable` as MediaPlayer on your [MediaController](http://developer.android.com/reference/android/widget/MediaController.html) like this:
```java
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
GifImageButton gib = new GifImageButton(this);
setContentView(gib);
gib.setImageResource(R.drawable.sample);
final MediaController mc = new MediaController(this);
mc.setMediaPlayer((GifDrawable) gib.getDrawable());
mc.setAnchorView(gib);
gib.setOnClickListener(new OnClickListener() {
@Override
public void onClick(View v) {
mc.show();
}
});
}
```
#### Retrieving GIF metadata
+ `getLoopCount()` - returns a loop count as defined in `NETSCAPE 2.0` extension
+ `getNumberOfFrames()` - returns number of frames (at least 1)
+ `getComment()` - returns comment text (`null` if GIF has no comment)
+ `getFrameByteCount()` - returns minimum number of bytes that can be used to store pixels of the single frame
+ `getAllocationByteCount()` - returns size (in bytes) of the allocated memory used to store pixels of given GifDrawable
+ `getInputSourceByteCount()` - returns length (in bytes) of the backing input data
+ `toString()` - returns human readable information about image size and number of frames (intended for debugging purpose)
#### Associating single `GifDrawable` instance with multiple `View`s
Normally single `GifDrawable` instance associated with multiple `View`s will animate only on the last one.
To solve that create `MultiCallback` instance, add `View`s to it and set callback for given drawable, eg.:
```java
MultiCallback multiCallback = new MultiCallback();
imageView.setImageDrawable(gifDrawable);
multiCallback.addView(imageView);
anotherImageView.setImageDrawable(gifDrawable);
multiCallback.addView(anotherImageView);
gifDrawable.setCallback(multiCallback);
```
#### Advanced
+ `recycle()` - provided to speed up freeing memory (like in `android.graphics.Bitmap`)
+ `isRecycled()` - checks whether drawable is recycled
+ `getError()` - returns last error details
## Upgrading from 1.2.3
Meaningful only if consumer proguard rules (bundled with library) are **not** used (they are used by default by Gradle).
+ Proguard rule has changed to `-keep public class pl.droidsonroids.gif.GifIOException{(int, java.lang.String);}`
## Upgrading from 1.1.17
1.1.17 is the last version supporting API level 8 (Froyo). Starting from 1.2.0 minimum API level is 9 (Gingerbread).
## Upgrading from 1.1.13
Handling of several edge cases has been changed:
+ `GifDrawable#getNumberOfFrames()` now returns 0 when `GifDrawable` is recycled
+ Information included in result of `GifDrawable#toString()` when `GifDrawable` is recycled now contains zeroes only
## Upgrading from 1.1.10
It is recommended (but not required) to call `LibraryLoader.initialize()` before using `GifDrawable`. `Context` is needed in some cases
when native libraries cannot be extracted normally. See [ReLinker](https://medium.com/keepsafe-engineering/the-perils-of-loading-native-libraries-on-android-befa49dce2db)
for more details.
If `LibraryLoader.initialize()` was not called and normal library loading fails, `Context` will be tried to be retrieved in fall back way which may not always work.
## Upgrading from 1.1.9
`int` parameter `loopNumber` has been added to `AnimationListener#onAnimationCompleted()`.
## Upgrading from 1.1.8
#### Proguard configuration not needed
Proguard configuration is now bundled with the library, you don't need to specify it yourself.
## Upgrading from 1.1.3
`src` XML attribute in `GifTextureView` has been renamed to `gifSource` to avoid possible conflicts with other libraries.
## Upgrading from 1.0.x
#### Proguard configuration update
Proguard configuration has changed to:
```
-keep public class pl.droidsonroids.gif.GifIOException{(int);}
-keep class pl.droidsonroids.gif.GifInfoHandle{(long,int,int,int);}
```
#### Drawable recycling behavior change
`GifDrawable` now uses `android.graphics.Bitmap` as frame buffer. Trying to access pixels (including drawing)
of recycled `GifDrawable` will cause `IllegalStateException` like in `Bitmap`.
#### Minimum SDK version changed
Minimum API level is now 8 (Android 2.2).
#### Rendering moved to background thread
Rendering is performed in background thread running independently from main thread so animation is running
even if drawable is not drawn. However rendering is not running if drawable is not visible, see [#setVisible()](http://developer.android.com/reference/android/graphics/drawable/Drawable.html#setVisible(boolean, boolean)).
That method can be used to control drawable visibility in cases when it is not already handled by Android framework.
## References
This library uses code from [GIFLib](http://giflib.sourceforge.net/) 5.1.3 and [SKIA](https://code.google.com/p/skia/).
### Projects using android-gif-drawable
[ImageFactory](https://github.com/Doctoror/ImageFactory)
[NativeScript Plugin by Brad Martin](https://github.com/bradmartin/nativescript-gif) available on [NPM](https://www.npmjs.com/package/nativescript-gif)
[Sketch](https://github.com/xiaopansky/Sketch) Powerful and comprehensive image loader on Android, with support for GIF, gesture zooming, block display super large image.
Want to include your project here? [Fill an issue](https://github.com/koral--/android-gif-drawable/issues/new)
## License
MIT License
See [LICENSE](LICENSE) file.