Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/harjot-oberai/VectorMaster

Dynamic control over vector drawables!
https://github.com/harjot-oberai/VectorMaster

android dynamic vector vector-drawable

Last synced: 4 months ago
JSON representation

Dynamic control over vector drawables!

Awesome Lists containing this project

README 

        



# VectorMaster

[![Platform](https://img.shields.io/badge/platform-Android-yellow.svg)](https://www.android.com)

[![API](https://img.shields.io/badge/API-16%2B-brightgreen.svg?style=flat)](https://android-arsenal.com/api?level=16)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)



This library introduces dynamic control over vector drawables. Each and every aspect of a vector drawable can be controlled dynamically *(via Java instances)*, using this library. 



Features :



- Control : Control every attribute related to `path`, `group`, `vector` and `clip-path` like **color**, **alpha**, **strokeWdith**, **translation**, **scale**, **rotation** etc.  

- Clip Paths : The library supports clip paths.

- Trimming : The library allows trimming of path by using `trimEnd`, `trimStart` and `trimOffset` parameters.



# Usage

Just add the following dependency in your app's `build.gradle`

```groovy

dependencies {

      compile 'com.sdsmdg.harjot:vectormaster:1.1.3'

}

```



# Background and Working

`VectorDrawables` are really helpful for removing scaling problem but they lack control. Most of the changes to vector drawables are only possible by creating an `AnimatedVectorDrawable` and also defining animations. All of this is good but lacks control that may be required during runtime. 



For example, if we need to change vector's properties *(Say, color)* based on a user action *(Say, if user is choosing the theme of app)*. We can achieve this using `AnimatedVectorDrawable` but only to an extent, this approach can't be used if user action leads to an infinite number of cases *(Say, if user picks up a random color for theme)* and we need to change property of the vector for each case. Thus we need a mechanism that can be used to change a vector's properties at runtime using basic methods like `setColor`, `setScale`, `setTranslation` etc. This is where this library comes in.



**The library works as follows :**

- First the `vector.xml`*(the `VectorDrawable` that we wish to control)*, is parsed using `XmlPullParser` and the attributes are stored in Models corresponding to the tag.

- `vector` attributes are stored in `VectorModel`, `group` attributes in `GroupModel`, `path` atrributes in `PathModel` and `clip-path` attributes in `ClipPathModel`. The hierarchy is as follows :




- The `pathData` in `PathModel` is then parsed using `PathParser.java`; It parses the string data and converts it into a `Path` object.

- All the transformations, scaling etc are done using **Matrices** after the `Path` object is built. All this is done prior to the first draw on canvas.

- At first draw we have the same output as we should have got if we used inbuilt methods to draw the `vector.xml` using `srcCompat`.

- Now, all Models are accessible via `getModelByName(...)` public methods that can be directly called via the instance of `VectorMasterView` that we get using `findViewById(...)`.

- If we wish to change any value, we just need to call `model.setParamter(...)`. `model` is of type `VectorModel`, `GroupModel`, `PathModel` or `ClipPathModel`. `parameter` can be anything like **color**, **scale**, **rotation** etc. depending on the model we are using.

- After setting a paramter the necesarry `paints` and `paths` are rebuilt, scaled, transformed etc.

- A call to `update` method repaints the canvas with the required changes.



# Examples



#### ic_heart.xml (This is the original vector that has been used in all examples)




```xml



    



```



## Example 1 (Simple Color change)

#### XML

```xml



```



#### Java

```java

VectorMasterView heartVector = (VectorMasterView) findViewById(R.id.heart_vector);



// find the correct path using name

PathModel outline = heartVector.getPathModelByName("outline");



// set the stroke color

outline.setStrokeColor(Color.parseColor("#ED4337"));



// set the fill color (if fill color is not set or is TRANSPARENT, then no fill is drawn)

outline.setFillColor(Color.parseColor("#ED4337"));

```



#### Result




## Example 2 (Trim paths)

#### XML

```xml



```



#### Java

```java

VectorMasterView heartVector = (VectorMasterView) findViewById(R.id.heart_vector);



// find the correct path using name

PathModel outline = heartVector.getPathModelByName("outline");



// set trim path start (values are given in fraction of length)

outline.setTrimPathStart(0.0f);



// set trim path end (values are given in fraction of length)

outline.setTrimPathEnd(0.65f);

```



#### Result




## Example 3 (Simple color animation using ValueAnimator)

#### XML

```xml



```



#### Java

```java

VectorMasterView heartVector = (VectorMasterView) findViewById(R.id.heart_vector);



// find the correct path using name

PathModel outline = heartVector.getPathModelByName("outline");



outline.setStrokeColor(Color.parseColor("#ED4337"));



heartVector.setOnClickListener(new View.OnClickListener() {

    @Override

    public void onClick(View view) {



    	// initialize valueAnimator and pass start and end color values

        ValueAnimator valueAnimator = ValueAnimator.ofObject(new ArgbEvaluator(), Color.WHITE, Color.parseColor("#ED4337"));

        valueAnimator.setDuration(1000);



        valueAnimator.addUpdateListener(new ValueAnimator.AnimatorUpdateListener() {

            @Override

            public void onAnimationUpdate(ValueAnimator valueAnimator) {



            	// set fill color and update view

                outline.setFillColor((Integer) valueAnimator.getAnimatedValue());

                heartVector.update();

            }

        });

        valueAnimator.start();

    }

});

```



#### Result




## Example 4 (Simple trim animation using ValueAnimator)

#### XML

```xml



```



#### Java

```java

VectorMasterView heartVector = (VectorMasterView) findViewById(R.id.heart_vector);



// find the correct path using name

PathModel outline = heartVector.getPathModelByName("outline");



outline.setStrokeColor(Color.parseColor("#ED4337"));

outline.setTrimPathEnd(0.0f);



heartVector.setOnClickListener(new View.OnClickListener() {

    @Override

    public void onClick(View view) {



    	// initialise valueAnimator and pass start and end float values

        ValueAnimator valueAnimator = ValueAnimator.ofFloat(0.0f, 1.0f);

        valueAnimator.setDuration(1000);



        valueAnimator.addUpdateListener(new ValueAnimator.AnimatorUpdateListener() {

            @Override

            public void onAnimationUpdate(ValueAnimator valueAnimator) {



            	// set trim end value and update view

                outline.setTrimPathEnd((Float) valueAnimator.getAnimatedValue());

                heartVector.update();

            }

        });

        valueAnimator.start();

    }

});

```



#### Result




# Complex animations

The above examples are just the basic use cases and are meant to serve as a quick start to using the library. For more complex animations and use cases involving **clip-paths** and **groups**, head to [AnimationExamples](AnimationExamples)





If your animation doesn't involve any `clip-path` or `group`, then you may use [RichPath](https://github.com/tarek360/RichPath) library developed by [tarek360](https://github.com/tarek360). This library is really useful, if you don't want to indulge in too much mathematics or logic.



# Using as a Custom Drawable

The library also provide custom drawable implementation in form of `VectorMasterDrawable`. It provides the same control over the vector, but allows the user to use the drawable as per its wish, for e.g. as a `Compound Drawable` in `TextView`, or as the source drawable in `ImageView`; basically any use case that involves a `Drawable` can be replaced by `VectorMasterDrawable`.



## Example

#### XML

```xml



```



#### Java

```java

// Instantiate the custom drawable

VectorMasterDrawable vectorMasterDrawable = new VectorMasterDrawable(this, R.drawable.ic_heart);



// Set top drawable for TextView

TextView textView = (TextView) findViewById(R.id.text_view);

textView.setCompoundDrawablesWithIntrinsicBounds(null, vectorMasterDrawable, null, null);



// Set background drawable for ImageView

ImageView imageView = (ImageView) findViewById(R.id.image_view);

imageView.setImageDrawable(vectorMasterDrawable);



// Set tht stroke color of the drawable

PathModel pathModel = vectorMasterDrawable.getPathModelByName("outline");

pathModel.setStrokeColor(Color.parseColor("#ED4337"));

```



#### Result




# Limitations

1. The `PathParser.java` has been extracted from Android source code of version 5.1.1. After this version all the parsing code was shifted to native for efficiency. I have incorporated some of the changes from the native code into the `PathParser.java`, but still sometimes parsing errors occur. I have also included a 3rd party parser from [Android-Image-Shape](https://github.com/sathishmscict/Android-Image-Shape/blob/master/library/src/main/java/com/github/siyamed/shapeimageview/path/parser/PathParser.java). To use this parser instead of the default one, set `use_legacy_parser="false"`. This may help in certain situations but not always. If you find any vector that is not being drawn properly, please file an issue and include the vector.

2. Path morphing is not supported as of now. I would like to support path morphing between incompatible vectors as well (using techniques mentioned [here](https://github.com/alexjlockwood/ShapeShifter#how-does-it-work) by [Alex Lockwood](https://github.com/alexjlockwood)).

3. Vector tints are not supported yet.

4. This library doesn't have dedicated methods for supporting animations. It just exposes the `paths`, `groups` etc. for the user to use as he wants, thus for making animations a lot of maths and logic is involved. If you want dedicated methods for animations use [RichPath](https://github.com/tarek360/RichPath) library developed by [tarek360](https://github.com/tarek360).



# License

VectorMaster is licensed under `MIT license`. View [license](LICENSE.md).