How To Use Canvas4Z

{{Template:Smalltalk_Author|
|author=Simon Pai, Engineer, Potix Corporation
|date=June 8, 2010
|version=ZK 5.0.2, Canvas4Z 0.8.0
}}

==What's Canvas4Z==
Canvas4Z is an experimental component that uses the power of HTML Canvas to draw various objects on any modern browser, including IE6. 

Enlightened by John Scattergood's idea (from [http://www.zebra.com/ Zebra]) to connect Canvas to Java 2D API, we've build this new prototype to expand ZK's reach on graphic functionality in the future.

==What can be done with Canvas4Z==
Before we even introduce what functions Canvas provides, let's see how we can play with it first.

<gflash width="980" height="637">2010-05-25-Canvas-Demo.swf</gflash>
* Note that even though IE 8 does not natively supports Canvas, you can still play the demo with IE, except that the text drawing function is disabled.

==How to use Canvas4Z==
===Add a Canvas in zul===
Like a regular component, in your zul file you can have:
<source lang="xml">
<canvas id="cvs" width="800px" height="500px" />
</source>
* Note that Canvas is always childless.


===Prepare Drawable objects===
Then, on server side, you can prepare Drawable items like:
<source lang="java">
// A rectangle at (50,100) with width 200px, height 300px
Drawable rectangle = new Rectangle(50, 100, 200, 300);

// A triangle
Drawable path = new Path().moveTo(50,50).lineTo(100,70).lineTo(70,100).lineTo(50,50).closePath();

// A piece of text at (100, 100)
Drawable text = new Text("ZK Canvas", 100, 100);
</source>
* The API of Rectangle and Path are similar to APIs of ''java.awt.geom.Rectangle2D'' and ''java.awt.geom.Path2D''


===Operate Drawables on Canvas===
You can add, insert, remove, or replace them on Canvas:
<source lang="java">
Canvas cvs = getFellow("cvs");
cvs.add(rectangle);
cvs.add(path);
cvs.add(1, text);
cvs.remove(0);
cvs.clear();
</source>
* The API is almost identical to Java List API
* Upon these actions, Canvas will show the changes by drawing/redrawing items on browser accordingly.


===Operate Java 2D Shapes on Canvas===
And why not just add some Java 2D Shapes directly into Canvas?
<source lang="java">
cvs.add(new Arc2D.Double(100, 100, 300, 300, 0, 270, Arc2D.PIE));
cvs.add(new RoundRectangle2D.Double(50, 50, 200, 400, 10, 10));
</source>


===Set drawing attributes on Drawables===
Prior to sending drawable items into Canvas, you can specify some drawing attributes on the items:
<source lang="java">
// sets colors
rectangle.fillStyle("#000080");
rectangle.strokeStyle("#0000FF");

// sets color transparency
rectangle.setAlpha(0.5);

// rotates the shape by setting transformation
rectangle.setTransformation(0.87, 0.5, -0.5, 0.87, 0, 0);

// sets outline width
rectangle.setLineWidth(5);

// sets shadow effect
rectangle.setShadowOffset(10, 10);
rectangle.setShadowColor("#808080");
rectangle.setShadowBlur(5);

// add whatever you want...

cvs.add(rectangle);

</source>
* Almost all attributes defined in HTML 5 Canvas spec are supported (as long as your browser supports it too).


===Client side programming===
You can do pretty much the same things on client side, too:
<source lang="javascript">
var cvs = jq('#cvs');

var rectangle = new zkforge.canvas.Rectangle(50, 50, 100, 100);
rectangle.setFillStyle("#808080");
rectangle.setAlpha(0.5);

cvs.add(rectangle);
</source>

==Download==
* [https://sourceforge.net/projects/zkforge/files/Small%20Talks/How%20To%20Use%20Canvas4Z/canvas4z.jar/download Canvas4Z Binary]
* [https://sourceforge.net/projects/zkforge/files/Small%20Talks/How%20To%20Use%20Canvas4Z/canvas4z.src.zip/download Canvas4Z Source Files]
* [https://sourceforge.net/projects/zkforge/files/Small%20Talks/How%20To%20Use%20Canvas4Z/Canvas4Z-Demo.war/download Demo (ZkossSoft Paint)]

==Summary==
Canvas opens a door to graphics on browser for ZK. By using its server and client side API together you can build many interesting application. Next time we will explore how we built this Paint demo using the concept of client-server fusion.


<center>[[Image:ruler.gif]]</center>
<comment>http://docs.zkoss.org/wiki/How_To_Use_Canvas4Z</comment>

[[Category:ZK]]
[[Category:Component Development]]
{{Template:Smalltalk_Footer|
|name=Potix Corporation
}}