Dive Into Dojo GFX

It’s well known that Dojo’s DojoX collection is a treasure trove of enterprise-ready, advanced widgets and JavaScript classes that allow you to accomplish difficult tasks with relative ease. One of DojoX’s most powerful features is GFX. Let’s dive into what GFX is, how to create feature-rich vector drawings with GFX, and how you can start creating vector graphics with GFX today!

What is GFX and Why Should Use It?

GFX is a cross-browser vector graphic creation library with support for SVG, VML, Silverlight, and Canvas. GFX detects the best method for drawing by analyzing browser capabilities and using the best method for drawing; you may also prioritize which drawing method should be used by GFX by defining a gfxRenderer setting:

GFX also relieves the developer and the user from needing an external plugin (i.e. Flash, Silverlight) to create and view vector graphics within the browser. GFX graphics can respond to events and can even feature gradients! What does that give us? GFX allows you to create dynamic, beautiful, and data-driven graphics on the client-side with ease.

There are several possible pieces to a GFX vector graphic; let’s take a moment to learn about each piece.

Creating the Surface / Canvas

Like any great painting, a defined virtual canvas or “surface” must first be provided. The surface may be any size that you’d like and will be drawn within the provided node argument:

Note that besides the DOM node, you don’t need to know anything about which HTML tags to use or attributes to provide — GFX does the work for you!

Creating Shapes

GFX provides a host of defined, frequently used shapes: Rect, Circle, Ellipse, Line, Polyline, Image, Text, TextPath, and Path. The surface object provides quick methods for creating each of these shapes, so let’s look at the syntax to create each shape.

Rect

The Rect shape allows you to create rectangles and squares on the canvas:

surface.createRect({x: 100, y: 50, width: 200, height: 100 });

The x and y properties are the starting point for the shape; the width and height properties define the shape’s height and width.

Circle

The Circle shape allows you to create perfect circles on the canvas:

surface.createCircle({ cx: 100, cy: 100, r:50 });

The cx and cy properties represent where the coordinates of the circle’s center; r represents the circle’s radius.

Ellipse

The Ellipse shape allows you to create more flexible, customized ellipses:

surface.createCircle({ cx: 100, cy: 100, rx:50, r:25 });

The cx and cy properties represent where the coordinates of the ellipse’s center; rx and ry represent the horizontal and vertical radii.

Image

The x and y properties are the starting point for the shape; the width and height properties define the shape’s height and width. The src property must be provided which points to the image, just as an img tag would.

Simple fills and strokes can be added in string name or hexadecimal format. Strokes and fills can be changed at any time with the setStroke and setFill methods. Simple fills are only the most basic of styles. GFX has long support linear gradients and recently added radial gradients. Linear gradients (which work from “top” to “bottom”) require x1, y1, x1, y2 coordinates, as well as a color parameter which represents an array of “stop” objects representing colors at specific parts of the the overall gradient:

GFX Animations!

One of the most amazing parts of GFX is the ability to animate shapes. Shape animation classes live within the dojox.gfx.fx namespace and look very much like the Dojo Fx API in as far as class arguments. dojox.gfx.fx classes include: animateFill, animateFont, animateStroke, and animateTransform. A sample animateTranform class usage to rotate a shape (or group) 360 degrees would look like:

The two examples above keep the same size ratio of the graphic. You are more than welcome to scale a graphic at any size you’d like.

GFX Events

A common theme among the Dojo Toolkit family is outstanding flexibility . The flexibility of dojo.connect method allows you to add event listeners to GFX shapes and groups. The shape.getEventSource method provides the “source element” of the event which is passed to the dojo.connect method:

dojo.connect(group.getEventSource(),"onclick",function() {
//our shape was clicked, now do something!
});

The example above adds a click listener to the shape group which rotates the group 360 degrees when clicked. You may execute any functionality you’d like when an event is fired.

Tip: Silverlight supports the following events: onclick, onmouseenter, onmouseleave, onmousedown, onmouseup, onmousemove, onkeydown, and onkeyup. If you want to target the broadest range of renderers, you are advised to restrict yourself to this list of events.

GFX Application: Creating the London Ajax Logo

Now that we’ve covered the basics of GFX graphic creation, we can create an animated, beautiful graphic. A simple graphic we can create is the London Ajax logo, for the popular user group (see video and slides at the end of this post). The first step in creating a graphic manually is visually identifying the different shapes within the static graphic you’re basing the soon-to-be-created GFX graphic. You can see the image is composed of:

An upside-down “V” which makes for the “A” shape; gradient from one red to another red.

A solid blue rectangle.

Solid white text shape with “London AJAX” verbiage.

This image is fairly simple but let’s break it down by steps.

Tip: To get the proper coordinates for each shape of the vector graphic, use a static graphic and grab the pixel dimensions/points. Photoshop and comparable tools are extremely helpful. Remember that you can scale the image larger or smaller using GFX, so a baseline is all you need.

Step 1: Create the Surface and Group

As always the first step is creating the surface. I want to create one graphic comprised of many shapes, so I will create a group right away:

Step 5: Fun! Events and Animation

To add a bit of fun to the the graphic, let’s add a click event to the graphic which will rotate the graphic 360 degrees, flip the gradient, and change the rectangle color. When the animation is complete, the graphic will be returned to its original state.

This animation is relatively simple but should give you a good representation of how you can assign events and animations to elements. DojoX’s charting library uses GFX events and animations for their Highlight, MoveSlice, and Magnify plugins.

Automated Graphic Creation

GFX features an XSL-based automated SVG parser which takes a static SVG graphic and turns it into a GFX graphic, allowing for size, color, and every other type of manipulation. I’ve covered this outstanding resource on my blog.

Who’s Using GFX?

Dojo’s powerful GFX solution has been used by many enterprise-level websites, most notably ESRI. ESRI has created a mapping system featuring Dojo’s GFX library; you may view an example here. Many clients use Dojo’s charting classes which are based on the GFX library. GFX’s power, stability, and flexibility have made it the perfect solution for creating beautiful vector graphics.

Tips for GFX Graphic Creation

A few tips for GFX graphic creation:

Internet Explorer’s native VML engine got progressively worse from IE6 to IE8. Silverlight may be the best option when manually setting the rendering priority.

If your drawing is not rendering properly in IE8, use the META tag method of emulating IE7:

Get Graphic with GFX!

GFX is an outstanding vector graphics library featuring what you’ve come to expect from the Dojo Toolkit: flexibility and dependability wrapped in a modular, well-written code structure. The powerful dojox.charting library uses GFX as its base, as does dojox.drawing and dojox.sketch. Vector graphic creation is a great way to avoid loading the same image at different sizes and create animatable graphics!

The following are a few companies known to us GFX in their products:
ESRI (their ArcGIS JavaScript API, link in the original article)
Arizona State University (Project Andes, for solving physics and mathematics homework problems
IBM
vmware (Spring)

http://mosaik-software.de Christian

yeah, looks awsome, wonder how to catch event in there?!

http://www.wissel.net/ Stephan H. Wissel

I just published a sample how to use GFX (very crude admitting) to draw burn charts (cool for agile project management) on my blog:http://www.wissel.net/blog/d6plinks/SHWL-8CLNBW
I’ll probably upgrade the code with things I learned in this blog entry
:-) stw

http://www.sitepen.com David Walsh

@Christian: Catching an event is shown within the “Step 5: Fun! Events and Animation” code snippet:

how to make a shape translate on the surface forever, and have a fluid feel?
with window.setInterval() i can let a shape translate forever, but it’s not smooth and no a fluid feel.

zhang

In fact, i want to reproduce the example of “particles and gravity” in the book “Foundation Silverlight 3 Animation”. I’ve spent several weeks, and was frustrated.
Do you think it’s posiible?
Or maybe you can write a “dive into dojo particles system”? :-)