|
1 | 1 | # CanvasScript |
2 | 2 | A canvas rendering wrapper for Android's Canvas and Paint classes |
3 | 3 |
|
| 4 | +[ ](https://bintray.com/52inc/CanvasScript/CanvasScript/_latestVersion) |
4 | 5 |
|
5 | 6 | ## Include |
6 | 7 | ```groovy |
7 | | -compile 'com.52inc:canvasscript:1.0.0' |
| 8 | +compile 'com.52inc:canvasscript:1.0.1' |
8 | 9 | ``` |
9 | 10 |
|
| 11 | +## How-to-Use |
| 12 | + |
| 13 | +There are two ways to to utilize the wrapper. |
| 14 | + |
| 15 | +1. **Creating a new Bitmap to render to** |
| 16 | + |
| 17 | +```java |
| 18 | +CanvasScript.create(int width, int height) |
| 19 | +CanvasScript.create(int width, int height, Bitmap.Config config) |
| 20 | +CanvasScript.create(Bitmap bitmap); |
| 21 | +``` |
| 22 | + |
| 23 | +This will create a new script object initialized with new (or provided) bitmap where all subsequent drawing calls will be rendered to and returned. |
| 24 | + |
| 25 | +2. **Wrap an existing canvas** |
| 26 | + |
| 27 | +```java |
| 28 | +CanvasScript.wrap(Canvas canvas) |
| 29 | +``` |
| 30 | + |
| 31 | +This will return a script instance wrapped around an existing `Canvas` (i.e. if you are trying to use the script to render in a custom view object) where all drawing calls will be directed and rendered to. |
| 32 | + |
| 33 | +- |
| 34 | + |
| 35 | +Once you have initialized your script object you can then start chaining drawing and paint calls that will be combined sequentially in the order they were called when you call the `.draw()` function. If you created your script using **Method #1** then it will return the provided/created `Bitmap` that was drawn upon. If you created your script using **Method #2** then it will return `null`. |
| 36 | + |
| 37 | +### Methods |
| 38 | +There are basically **two** groups of methods: **Paint** methods, and **Canvas** Methods. |
| 39 | + |
| 40 | +#### Paint |
| 41 | + |
| 42 | +These methods modify an internally tracked `Paint` object that can be implicitly provided for all the `Canvas` drawing calls so you don't have to keep track of creating and supplying your own (unless you want to). |
| 43 | + |
| 44 | +[`CanvasScript.java L151 - L355`](https://github.com/52inc/CanvasScript/blob/master/library/src/main/java/com/ftinc/canvasscript/CanvasScript.java#L151-L355) |
| 45 | + |
| 46 | +One of these methods must be called to initialize the internal paint object before calling and implicity canvas method or else you will get an `IllegalStateException` |
| 47 | + |
| 48 | +#### Canvas |
| 49 | + |
| 50 | +These methods are instructions for calls to the `Canvas` object to be rendered sequentially: |
| 51 | + |
| 52 | + |
| 53 | +[`CanvasScript.java L358 - L1457`](https://github.com/52inc/CanvasScript/blob/master/library/src/main/java/com/ftinc/canvasscript/CanvasScript.java#L358-L1457) |
| 54 | + |
| 55 | +There is a version of every call to account for all possible drawing methods for their `Canvas` equivelents. There is also a duplicate call where you can supply your own `Paint` object for rendering instead of using the internally tracked one mentioned above. |
| 56 | + |
| 57 | +#### Special |
| 58 | + |
| 59 | +Now there are a few special methods in the API to give you some extra functionality and they are: |
| 60 | + |
| 61 | +```java |
| 62 | +public CanvasScript custom(@NonNull CanvasParams customParameter) |
| 63 | +``` |
| 64 | + |
| 65 | +This call allows you to provide a custom `CanvasParams` object where you can define a custom set of `Canvas` drawing calls to the stack (i.e. If you wanted to create a parameter that auto magically sets up a PorterDuff Xfer call in one line) |
| 66 | + |
| 67 | +```java |
| 68 | +public CanvasScript script(CanvasScript script) |
| 69 | +public CanvasScript script(float dx, float dy, CanvasScript script) |
| 70 | +``` |
| 71 | + |
| 72 | +These calls allow you to chain multiple `CanvasScripts` together |
| 73 | + |
| 74 | +### Drawing |
| 75 | + |
| 76 | +Once you have finished your chain of paint and canvas methods and are reading to render everything to the canvas/bitmap just call: |
| 77 | + |
| 78 | +```java |
| 79 | +@Nullable |
| 80 | +public Bitmap draw() |
| 81 | +``` |
| 82 | + |
| 83 | +If you wrapped an existing `Canvas` object when you created your `CanvasScript` then this will return `null`, otherwise it will return the `Bitmap` that it created will all the subsequent drawing calls made to it. |
| 84 | + |
| 85 | +##### Special note about save/restore calls |
| 86 | + |
| 87 | +If you make any `Canvas` save calls (i.e. `save()`, `saveLayer(...)`, etc) the CanvasScript will internally keep track of the returned integer (i.e. the save count) so when you later call `restore()` it will automatically restore to that saved count. |
| 88 | + |
| 89 | +### Example |
| 90 | + |
| 91 | +```java |
| 92 | +CanvasScript.wrap(canvas) |
| 93 | + .saveLayer() |
| 94 | + .bitmap(image, measuredWidth, measuredHeight) |
| 95 | + .porterDuffXfer(PorterDuff.Mode.CLEAR) |
| 96 | + .circle(measuredWidth/2f, measuredHeight/2f, measuredWidth/4f) |
| 97 | + .paint(null) |
| 98 | + .restore() |
| 99 | + .color(color(R.color.colorAccent)) |
| 100 | + .alpha(0.5f) |
| 101 | + .rect(0f, 0f, measuredWidth/2f, measuredHeight/2f) |
| 102 | + .alpha(1f) |
| 103 | + .color(Color.BLUE) |
| 104 | + .roundedRect(measuredWidth/2f, measuredHeight/2f, measuredWidth.toFloat(), measuredHeight.toFloat(), 20f) |
| 105 | + .color(Color.YELLOW) |
| 106 | + .style(Paint.Style.STROKE) |
| 107 | + .strokeWidth(10f) |
| 108 | + .strokeCap(Paint.Cap.ROUND) |
| 109 | + .arc(20f, 20f, measuredWidth.toFloat() - 40f, measuredHeight.toFloat() - 40f, -135f, 90f, false) |
| 110 | + .draw() |
| 111 | +``` |
| 112 | + |
| 113 | +The result looks like this: |
| 114 | + |
| 115 | +<img src="art/example.png" style="width: 400px"></img> |
0 commit comments