How to use the new clip property

`

Video transcript

Here's the transcript of the video that you can see above. It introduces you to the new clip property which enables you to easily create combined charts.

In this video I'm going to explain and show you an example of the new clip property that has been added to version 6.17 of RGraph - a very useful new feature that's available to both canvas and svg charts. It allows you to restrict what gets drawn on the canvas or svg tag and opens up a range of possibilities when it comes to combining similar or different charts. The most common combination is a multi-color Line chart based on the scale where 0-5 might be colored red, 5-15 would be colored yellow and 15-100 colored green. This sort of chart was easily feasible before this new property was introduced but now that it's available it becomes a very simple affair indeed.

Here's an example Line chart that shows the value in different colors based on the scale value and this is achieved by specifying three different Line charts, one for each color, with the clip property set to clip based on the scale value. The source code of the chart has three separate RGraph Line charts configured. The first sets up the configuration of the chart and the subsequent Line charts copy this configuration using the javascript spread operator but override the colors with their own. So each chart will show its own part of the chart in a different color and the end result is a multi-colored Line chart like this.

So how do you use it? It's just a normal RGraph property that you specify in the configuration of your chart just like any other property. It can be set to a number of different things - allowing you to clip the canvas or svg tag in a variety of different ways. These include:

tophalf: This clips the tag to the top half of the drawing area. Different sizes of margin are taken into account so if your top margin is larger or smaller than your bottom margin then the center point will not be the dead center of the drawing area.

bottomhalf: This clips the tag to the bottom half of the drawing area. Again, margins are taken into account.

lefthalf: This clips the tag to the left half of the drawing area. Margins are taken into account.

righthalf: This clips the tag to the right half of the drawing area. Margins are taken into account.

Clipping to a rectangle: An array of four numbers - x, y, width and height which form the coordinates and size of a rectangle.

Clipping to a circle: Clip the drawing area to a circle that's described by three numbers - the x and y coordinates of the center point along with the radius of the circle.

Clipping to a polygon: You can give an array of coordinates - these coordinates are arrays containing two numbers - ie XY coordinates - which form a polygon that the drawing area is clipped to.

Clipping to a segment: You can clip to a segment - part of a circle - using this option. You give the XY coordinates of the center-point, the radius of the segment and the start and end angles of the segment, which can be given in both degrees and radians. By default, the angles are measured in radians.

Clipping to an RGraph path string: Since the canvas path syntax is very verbose RGraph, for a long time, has provided the ability to use a much shorter form - much like the svg path syntax but more versatile. This shortened path syntax accommodates doing the majority of the canvas functions and by using this as a clipping option you can clip to some very weird and wonderful shapes!

Clipping to percentages of the x-axis: If you're making a dual-color Bar chart, for example, you can use this option to clip to certain percentages of the x-axis so the first two bars of a Bar chart with 8 bars in total could be one color and the other 6 bars another color. There are two keywords - min and max - that you may want to use instead of zero and 100 because if you clip to 0 or 100 then the margins will not be included and your chart may therefore be missing the labels.

Clipping to percentages of the y-axis: If you're making a dual-color Line chart, for example, you can use this option to clip to certain percentages of the y-axis so the top 10% of the scale uses a red color, the next 20% uses yellow and the remaining 70% is colored green. There are two keywords - min and max - that you may want to use instead of zero and 100 because if you clip to 0 or 100 then the margins will not be included and your chart may therefore be missing some labels.

Clipping to percentages of the radius: For circular charts, using this option allows you to clip to percentages of the radius. You can again use the min and max keywords but the min keyword is no different to using 0. You can use this option with the circular charts which have a radius.

Clipping to scale values: Most of the charts have scales and a useful option that you have is being able to clip to those scales. So on a Line chart you want to show 0-5 in red, 5-15 in yellow and 15-100 in green. Using this option you can do just that. Instead of 0 you can use the keyword min in order to include the margin and likewise to include the top margin you can use the keyword max.

There are a number of demos available to in the demos folder of the download archive. Most of the demos include the word clipping in their name but a few don't. There's a list of some of the demos that are available on the clipping documentation page.

A few demos that show clipping and its uses and that are definitely worth looking at are:

svg-line-clipped4.html - This demo shows an interesting way to compare two Line charts by sliding the mouse left and right. Another use of this technique would be to turn off the axes, the background grid and the scale and give the charts an empty dataset. Then, specify two similar looking pictures as each of the charts background images. You'll then be able to easily compare the images (for example two pictures of a street, one old and the other up-to-date) simply by moving the mouse left and right over the svg or canvas tag.

svg-line-clipped3.html - This demo has limited use but is rather fun to play with. It clips the drawing area to a circle which is centered on the mouse coordinates. As the mouse moves - so does the circle around the mouse pointer and thus the bit of the chart that you can see. As I say - limited use!

line-banded-gradient-clipping.html - A canvas filled Line chart where both the fill-color and the stroke-color is different based on the value of the line. So it's one color up to 2.5, another up to 5, another up to 7.5 and one more up to the maximum 10. In order for the x-axis labels and the key to be shown (the key is positioned in the top margin) the keywords min and max are used.

In conclusion, the multi-colored Line chart is definitely a very useful application of this new property but you may have more uses for it so just try experimenting with it!