Introduction

A lot of my past widgets have used graphs. It has paid off to write some reusable code for creating graphs in my widgets. I recently realized that with a little bit of polish, these libraries could be used in any widget with relatively little effor.

Graphing is a great way to display large amounts of numerical information. It also adds visual flair to your widget. There is a downside, though. Graphs use a relatively large amount of system resources (processor time, RAM) compared to text. When you use graphs, you have to balance the upsides with the downsides. Avoid using too many graphs, or your system will slow to a crawl.

I created a number of different types of graphs for you to use.

Part 1: Regular (Cartesian) Graphs

Types of Graph

There are four basic types of graphs included in the graphs.js library. They each have their advantages and disadvantages.

Pixel Graph - This type of graph shows simple lines connecting each point on the graph. It kind of looks like an old pen plotter graph. It is light on processor usage, but looks a bit better than a solid graph. Every data point takes two pixels, so a 100 pixel wide graph can hold 50 data points. The fancy option turns on shading below the main line. This graph is great for clearly displaying graph points, in a compact format.

Solid Graph - This is the simplest type of graph. It uses the least processor time to render. It also holds the most information. However, depending on what you are using it for, it can look very busy and unattractive. Each data point takes up only 1 pixel, so a 100 pixel graph can hold 100 data points. The fancy option makes the opacity of each datum proportional to its height, so that smaller values are lighter, and higher values are more opaque.

Bar Graph - This type of graph is good for things that are not updated very often. It is relatively light on processor usage, but not very information dense. Each data point takes up 5 pixels, so a 100 pixel wide graph will only hold 20 data points. The fancy option makes each bar's opacity proportional to its value, so high values are darker, and low values are lighter. With the plain option, all bars are opaque.

Area Graph - This type of graph is the most processor intensive. It is also not information dense. Each data point takes up five pixels, so a 100 pixel wide graph only holds 20 data points. Its redeeming feature is that it looks really freaking cool. I recommend this for large graphs that will be updated relatively rarely. It also looks best if your data has lots of variation. The fancy option turns on shading below the main graph line. With the plain option, only the main line is drawn. Be careful not to use too many of these graphs, they really can eat up your system resources.

Creating a Graph Object

In the graph.js library, each graph is a object, like a string or an array. An object contains behaviors and data. Although the internals of the graph.js library is very complex, using it is very simple. To create a new graph, you need to use only one line:

All properties must be included when you create the graph, with the exception of fancyOption, which is optional. The properties are explained as follows:

hOffset - The number of pixels from the left side of the parent frame the graph should be located. This is measured from the left side of the graph.

vOffset - The number of pixels from the top of the parent frame the graph should be located. This is measured from the top of the graph.

width - The width of the graph in pixels. The width also defines the number of data points of your graph. The wider the graph, the more information that can be displayed.

height - The height of the graph in pixels. The taller the graph, the easier it is to tell each data point apart.

type - The type variable should be a string with one of four options. "pixel", "solid", "bar", or "area". These different types were explained above. The type variable MUST contain one of these four options, or your graph will not be created.

color - The color variable contains a string with the standard RGB color to be used for the graph. It should look something like "#FF0000". There must be a "#" sign at the beginning of the string. Leaving the string blank (i.e. using the string "") will default the graph to red.

frame - The frame variable contains the name of the frame that the graph will be put into. This must not be left blank. In simple widgets, there is usually only one frame.

fancyOption - The fancy option is the only optional variable. If you don't include it, the graph will default to the "plain" option. If you set the fancyOption to 1, then the graph will display in "fancy" mode.

When you have created the graph, you should see it appear on your widget. If you don't see the graph, you have done something wrong.

Updating the Graph

Updating the graph is also very simple. All you have to do is call a behavior of your graph object.

The value variable should be an integer between 0 and 100. Any values above or below this will be set to 100 or 0, respectively. This function updates the rightmost datapoint on your graph to your new value, and moves the other data points left. The leftmost data point will disappear from the graph. This method is useful for a graph that will be updated frequently, like a processor usage graph.

There is a second method for updating the graph.

If you pass the update() function an array of integers, it will push all those numbers into the graph. This is good for populating a graph all at once. If you include more numbers in your array then there are datapoints on the graph, only the later data points will be displayed. The integer values in the array must be between 0 and 100.

Nifty Ideas for Graphs

Each graph only contains one "line". However, since graphs are transparent, you can stack several graphs right on top of each other. This will make a graph with multiple lines.

The graph.js library is pretty flexable by default. However, if you know what you are doing, you can customize the graphs even further. You might even be able to port this javascript over, so that it runs in a web browser instead of the Yahoo Widget Engine. I welcome creative uses of the graph.js library, as long as credit is given to me in your "About" page on your widget, and in your code, in comment form. Using this library without crediting me, downloading this library from a site other than jozerworx.com, or using this library for commercial purposes without my explicit permission is forbiddin.

 

Pie Graphs

Introduction

The graph.js libray also contains support for pie graphs, also known as pie charts. This is included in a separate file, "pieGraph.js". Using pie graphs is very similar to using the regular cartesian graphs. Please be aware that pie graphs use MUCH MUCH more system resources than any of the regular graphs. Do not use to many pie graphs, or update the very frequently, or the system performance will degrade very quickly.

Creating a Pie Graph

Like the cartesian graphs, you only need to use one line to create a pie graph. Unlike a cartesian graph, a freshly create pie graph does not "appear" immediately after you create it. You must update the graph with a value before any "slices" of pie appear.

Below is an explanation of the properties needed to create the pie graph.

hOffset - The number of pixels from the left side of the parent frame the graph should appear. This is measured from the left side of the graph.

vOffset - The number of pixesl from the top of the parent frame the graph should appear. This is measured from the top of the graph.

diameter - The number of pixels the diameter of the graph should be. I recomend a maximum of 100px, any bigger and the quality of the graphics will degrade.

color - This is a string that contains a standard RGB color. It will look something like this "#FF0000". The "#" sign must be included at the begging of the string. If the color value included is not valid, the graph will default to red.

frame - This is a string that contains the name of the frame the graph should be created in. This value MUST be correct or the graph will not appear.

fancyOption - This option displays the "circle" instead of "pie" style graph.

Updating a Pie Graph

Updating a pie graph has a few differences from a regular graph. You can only pass one value at a time to a pie graph. Sending an array will not work. The reason for this is obvious, the pie graph can only display one value at a time.

There are two arguments for the update function. The first is an integer number between 0 and 100. This will be the "percent full" size of your pie graph. Entering 100 will display a full circle, entering 0 will display nothing.

The second number is the rotation of the entire graph. If you leave the rotation valurable blank, the pie grpah will default to 0 degrees. The graph proceeds clockwise from the 3 o'clock position, so entering "50" for number will show the bottom half of a circle. Changing the rotaion enables a number of creative options that will addressed later.

Updating a pie graph requires a large amount of processing power. Avoid updating the graph too frequently. The example widget does not follow this advice, and if you watch its process in the task manager, you will see that it can use 10% or more of your processing power.

 

Sample Widget

Below is a screenshot of the graph widget. It shows all the various permutations of graph styles, as well as a few ideas on how to create more complex plots using multiple stacked graphs. The code is simple and commented for your convienence. This widget was created to teach you how to use the graph.js function. I ask that you credit me on the about screen of any widget that uses my code. If you widget is going to be used for commercial purposes, please contact me before using my code.