Attribute Reference for Annotations - FusionCharts XT Suite Documentation

This section covers the exhaustive set of configurations (attributes) supported by annotations of FusionCharts Suite XT.

General Configuration

The root annotation object, in data source, accepts a number of attributes to configure generic aspects of annotations.

These attributes can be provided within { annotations: { ... } } object of source data json.

Attribute Name	Description
`autoScale`	Determines whether annotations scale automatically as charts are resized after being rendered. Automatic scaling for all annotations is enabled by default and can be turned off by setting its value to `0`.
`constrainScale`	Setting this attribute determines whether automatic scaling of annotations preserves aspect ratio or not.
`scaleText`	By default, resizing of the chart results in auto-scaling of the annotations to not be applied on text annotations. Setting `0` for this attribute scales the text along with the rest of annotation items.
`scaleImages`	Images are not automatically scaled when resizing of a chart auto-scales the rest of the annotations. In order to enable scaling of images, this attribute must be set to `1`.
`xShift`	The value of this attribute is added to the x-coordinate position value of the final annotation items. In other words, if an annotation is placed at 100 pixels left and the value of `xShift` is set to 50, then the effective value of `x` for annotation adds up to 150 pixels. When applying scaling, the value of this attribute is included within the scale factor.
`yShift`	This attribute behaves similarly to the attribute `xShift` but applies to y-coordinate.
`grpXShift`	This attribute shifts all annotation groups along the x-coordinate. The difference between `xShift` and this attribute is that during scaling, `xShift` is included within the scale factor whereas `grpXShift` is excluded.
`grpYShift`	This attribute behaves similarly to the attribute `gryXShift` but applies to y-coordinate.
`origW`	This attribute helps you define the original width of the chart - the width of the chart with respect to which you have created the annotations. This is the reference design width that is used while automatically scaling annotations in the event a chart is resized. Let's say that during annotation design, the width of the chart was `300` pixels and then later it is changed to `600` pixels. As such, to retain the annotations' dimensions and positions to this change of chart size, setting `"origW": "300"` would let the `autoScale` feature resize and reposition the annotations appropriately.
`origH`	This attribute behaves like the `origW` attribute except that it applies to rescaling of chart height instead of width.

Configuring Annotation Groups

Annotation group accepts a number of attributes to configure itself and also accepts attributes to uniformly configure all annotation items contained within it. Default values of attributes for groups are inherited from the ones provided as root-level annotation attributes.

These attributes can be provided within objects inside groups array of { annotations: { groups: [ { ... }, { ... }] } of source data json.

Attribute Name	Description
`id`	Providing a unique `Id` to annotation groups allows one to programmatically access this group. Without a unique `Id` the entire annotation group becomes inaccessible using annotation related JavaScript API.
`x`	This attribute sets the x-origin of a group in pixels. All the annotations in the group will treat this value as the starting point. Thus, when you have to re-position a group of annotations, instead of re-positioning each and every annotation in the group, we can reposition the entire annotation group itself using this attribute.
`y`	This attribute is similar to the attribute `x` but is applicable to the y-coordinate.
`showBelow`	This attribute configures whether the annotation items rendered within the group is placed below the chart or the gauge. As default, annotations are drawn above a chart or gauge.
`autoScale`	Determines whether annotations scale automatically as charts are resized after being rendered. Automatic scaling for all annotations is enabled by default and can be turned off for specific annotation groups by setting its value to `0`.
`constrainScale`	Setting this attribute determines whether automatic scaling of annotations within the group preserves aspect ratio or not.
`scaleText`	By default, resizing of the chart results in auto-scaling of the annotations to not be applied on text annotations. Setting `0` for this attribute scales the text within the group along with the rest of annotation items.
`scaleImages`	Images are not automatically scaled when resizing of a chart auto-scales the rest of the annotations. In order to enable scaling of images, this attribute must be set to `1`.
`xShift`	The value of this attribute is added to the x-coordinate position value of the final annotation items. In other words, if an annotation is placed at 100 pixels left and the value of `xShift` is set to 50, then the effective value of `x` for annotation adds up to 150 pixels. When applying scaling, the value of this attribute is included within the scale factor.
`yShift`	This attribute behaves similarly to the attribute `xShift` but applies to y-coordinate.
`grpXShift`	This attribute shifts the annotation group along the x-coordinate. The difference between `xShift` and this attribute is that during scaling, `xShift` is included within the scale factor whereas `grpXShift` is excluded.
`grpYShift`	This attribute behaves similarly to the attribute `gryXShift` but applies to y-coordinate.
`link`	Allow users to click on particular annotations and perform actions such as open an URL or execute a JavaScript function. Annotations can also execute automatic drill-down using LinkedCharts specification provided to this attribute. When `link` is provided to an annotation group, all annotation items within this group get linked. To know more on the format of setting link attribute, read Setting Up Drill-down.
`color`	Set the color, in hex format, of all annotation items within the group.
`alpha`	Set the opacity of annotation items in the group. Setting `0` makes all annotation items completely transparent and `100` sets them to be opaque. Note that when opacity is provided at group level and also on individual annotation item, the effective opacity is set by what is provided on the annotation item.
`visible`	This attribute allows one to hide the group without adjusting various opacity settings. This is a very useful attribute in case your annotation has any form of show/hide toggle interaction.
`showShadow`	When set to `1`, all annotation items within the group shows a shadow under them.
`toolText`	Setting a text for this attribute enables a common tooltip text for all annotation items in the group.
`font`	All text type annotation items will inherit this font family value when `font` is set at the group level.
`fontSize`	All text type annotation items will inherit this font size when `fontSize` is set at the group level.
`textAlign`	All text type annotation items will inherit this horizontal text alignment when `textAlign` is set at the group level. This attribute accepts `left`, `right` and `center` as its value - the default being center aligned.
`textVAlign`	All text type annotation items will inherit this vertical text alignment when `textVAlign` is set at the group level. This attribute accepts `top`, `bottom` and `middle` as its value - the default being middle aligned.
`rotateText`	Setting `1` for this value rotates the text by `180` degrees, making texts within this group to render vertically.
`wrapText`	As default, annotation texts are not bounded. This means that unless the text itself contains a line-break `{br}`, no word wrapping is performed on the text. However, when a text annotation item is bounded by setting `toX`, `toY` on the text item, texts are wrapped to be contained within these bounds. This feature can be turned off by setting `wrapText` to `0`.

Customising Annotation Items

We have segregated this list of attributes into two parts for the sake of simplicity - attributes that work on all types of annotations and attributes specific to certain type of annotations. For example, the attributes x and y can be applied to all annotation items whereas, the attribute fontBold makes sense only when the annotation is of "type": "text".

These attributes can be provided within objects inside items array of { annotations: { groups: [ { items: [ { ... }, { ... } ] }, { items: [ { ... }, { ... } ] }] } of source data json.

Attributes common to all annotation items

Attribute Name	Description
`id`	Providing a unique `Id` to annotation items allows one to programmatically access this annotation item. Without a unique `Id` the annotation item becomes inaccessible using annotation related JavaScript API.
`type`	Sets the nature of shape the annotation item should represent - `line`, `rectangle`, `circle`, `arc`, `polygon`, `path`, `text` and `image`.
`x`	Using this attribute the x-coordinate (horizontal position) of an annotation item can be set. The value passed on to this is accepted in `pixels` and relative to the origin coordinates of the annotation group within which it resides. This attribute supports auto scaling and macro expressions. In case of `circle`, `arc` and `polygon` type annotation, it refers to the center x-coordinate. In case of `text`, the horizontal and vertical alignment of the text determines what origin this attribute represents. For example, a horizontally left and vertically bottom aligned text, this attribute represents the top-left coordinate. For a path, it represents the top left corner.
`y`	This attribute is similar to the attribute `x` but is applicable to the y-coordinate.
`toX`	For shapes such as `rectangle`, `line` that require two points for being drawn, this attribute defines the final x-coordinate. For example, specifying `"x": "300", "toX": "600"` (and a `y` coordinate) will draw a line from 300 pixel point to 600 pixel point horizontally. `toX` also determines the wrapping dimension when provided to a `text` type annotation and the scale factor when passed to an `image` and `path` type annotation.
`toY`	This attribute is similar to the attribute `toX` but is applicable to the y-coordinate.
`fillColor`	Determines the color of the annotation item in hex color format prefixed by `#` (Example `"fillColor": "#ffcc66"`). It even accepts multiple comma separated colors for specifying gradients. (Example `"fillColor": "#ffcc66,#2deaff,#a6992a"`.) Note that gradient fill is not applicable to `line`, `text` and `image` type of annotations.
`fillAlpha`	Determines the opacity of the `fillColor` of an element where `0` is transparent and `100` is fully opaque. It accepts multiple comma-separated opacities to set opacities of multiple colors provided as gradient to the `fillColor` attribute. In case the number of opacity values is lesser than the number of colors provided, the last of the comma-separated values is repeated.
`fillRatio`	This attribute is used to define the ratio of multiple colors when provided as comma-separated gradient to the `fillColor` attribute. It accepts numbers between `0` and `100` where the summation of all ratio values should add up to `100`. In case the number of ratio values is lesser than the number of colors provided, the remaining space (if any) is equally distributed between the extra colors. Say we had three colored gradient `"fillColor": "#ffcc66,#2deaff,#a6992a"` and we wanted to distribute first two colors within first half of the annotation and allocate the rest to the last. The ratio would look like `"fillRatio": "0,25,50"`.
`fillAngle`	For a gradient `fillColor`, this determines the angle in which the gradient will be drawn. It accepts one number between `0` to `360` in degrees.
`fillPattern`	Using this attribute, one can define whether the gradient fill will be `linear` or `radial`. Note that for circular annotations such as `circle` and `arc` this is `radial` by default.
`showBorder`	Setting this attribute to `1` will cause the annotation item to show a border around itself. Setting the `borderColor` automatically enables the border and as such this attribute is handy when an enabled border needs to be hidden.
`borderColor`	Defines the color of the border of an annotation item and it accepts value in hexadecimal format prefixed by `#`.
`borderAlpha`	Determines the opacity of the border of an annotation item where `0` is transparent and `100` being fully opaque.
`borderThickness`	The thickness, in `pixels`, of the border of an annotation item is specified using this attribute. By default, the border thickness is 1 pixel.
`dashed`	The border of an annotation item can be made to appear "dashed" (broken lines) when this attribute is set to `1`.
`dashLen`	In case of a dashed border, the length of the segments of dashes can be specified in pixels using this attribute.
`dashGap`	In case of a dashed border, the distance between the segments of dashes can be specified in pixels using this attribute.
`toolText`	One can cause an annotation item to show a tooltip when hovered over it using a mouse (or tapped on a touch device) by using this attribute. The tooltip color and other cosmetics are common for all tooltips within one chart and more on that is specified in the article Tooltips.
`link`	Allow users to click on particular annotations and perform actions such as open an URL or execute a JavaScript function. Annotations can also execute automatic drill-down using LinkedCharts specification provided to this attribute. To know more on the format of setting link attribute, read Setting Up Drill-down.
`showShadow`	When set to `1`, a shadow is drawn under the annotation item.

Attributes for specific annotation types

Annotation Type	Attribute Name	Description
`line`	`thickness`	A line between two points can accept a thickness value in pixels. By default a line is composed `2 pixel` thickness, but influence from `autoScale`, `xScale` and `yScale` can affect the effective thickness.
`circle`	`radius`	The radius of a circle can be controlled with respect to its center `x` and `y` using this attribute. This attribute accepts value in pixels.
	`startAngle`	A circle can be made to appear like a wedge by providing start and end angles (in `degrees`). For example, providing `0` for `startAngle` and `180` as `endAngle` draws a semi circle. On the same note, providing `"endAngle": "45"` will draw a wedge like a pizza slice!
	`endAngle`	`endAngle` attribute on a circle works in conjunction with `startAngle` to provide a wedge-like form to a circle.
	`yRadius`	Oval shape can be drawn using the `yRadius` attribute on a circle. This attribute accepts the secondary radius of the circle allowing an oval or an elliptical shape to be drawn. By default if this attribute is not provided, `yRadius` equates to `radius` and a perfect circle is drawn.
`arc`	`radius`	The `radius` attribute of an arc works similar to the `radius` attribute of a circle. It defines the size of the arc with respect to the central `x` and `y` coordinates.
	`innerRadius`	An arc is drawn to represent a doughnut like shape (or a part of it.) The `innerRadius` attribute defines the size of the void within the the inner side of the doughnut. For example, providing `"innerRadius": "0"` will actually draw a full circle. By default, the inner radius of an arc is set to eighty percent of the arc radius provided.
	`startAngle`	This attribute is used to set the starting angle for an arc (similar to that of a circle). For example, if you need to draw a semicircle or a semicircular arc, then set `"startAngle": "0"` and `"endAngle": "180"` for the respective annotation.
	`endAngle`	`endAngle` works similar to the `startAngle` but is used to define the end point of drawing of an arc.
`rectangle`	`radius`	The `radius` attribute, when set on a rectangle, configures the corner radius of its four edges.
`image`	`url`	The `url` attribute of an image type annotation is used to define the location of the image file (jpeg, png or gif) that needs to be rendered on the chart or gauge. Note that the chart rendering does not pause for the image to load and as such asynchronously draws them as and when they are loaded. In case you need to load them instantaneously, you may considering preloading the images.
`polygon`	`sides`	This attribute sets the number of sides that the required polygon will have. For example, to draw a triangle we need to set it to `3`. Similarly, to draw a pentagon, you can set it as `5`. A value of `sides` less than `3` draws a circle.
	`radius`	The `radius` of a polygon is the distance between its `x, y` center and its corners. The polygon drawn is always enclosed within the radius specified.
	`startAngle`	`startAngle` for a polygon defines the point from where the drawing of the polygon starts. The first corner of the polygon lies on the point resulting out of the radius and this starting angle.
`path`	`path`	The `path` type of annotation item allows you to draw free-from path. This attribute accepts standard `SVG` path format. An example path would be `"M 10, 10, L 100, 100"`. This signifies that we start drawing from (10,10) pixel coordinate using `M` command and draw a line till (100,100) pixel coordinate as specified by the `L` command.
`text`	`label`	Text content of this type of annotation is set using the `label` attribute. It also accepts `{br}` short-code for introducing line breaks.
	`align`	Texts are by default horizontally aligned in `center` with respect to the `x, y` attributes provided. One can set the value of `align` attribute to `left` or `right` to change the alignment of text.
	`vAlign`	This attribute stands for vertical alignment of text. Setting the value of this attribute to `top` or `bottom` causes the text to be vertically aligned above or below the `x, y` point respectively. By default, text is aligned vertically in `middle`.
	`font`	Font face or family of the text type annotation can be set using this attribute. The default of this attribute corresponds to what the `baseFont` of the chart has been set to (defaults to `Verdana`.)
	`fontSize`	The size of the font, in `pixels`, can be set using this attribute. The default of this attribute corresponds to what the `baseFontSize` of the chart has been set to.
	`fontColor`	The text color in hex format, `#` prefixed, can be set using this attribute. The default of this attribute corresponds to the `baseFontColor` of the chart.
	`bold`	The font face can be made to appear stronger when `"bold": "1"` is set.
	`italic`	The font style can be made to have emphasis (forward slant) when `"italic": "1"` is set.
	`leftMargin`	This attribute is very useful in setting a fixed margin, in `pixels` to the left of the text.
	`bgColor`	A text can be made to have a solid background by setting this property to the color value in hex format.
	`rotateText`	Setting the value of this attribute to `cw` or `ccw` will cause the text rotate by 90 degrees around the `x, y` coordinates of the text in clockwise and counterclockwise directions respectively.
	`wrapWidth`	Texts are not automatically wrapped by default - it expects the `{br}` short-code for line breaks. However, setting the wrapping dimension by `wrapWidth` will cause the text to break into new line when this width is reached. The `toX` and `toY` attributes can also be set on text if one intends to provide text wrapping in absolute pixels from annotation group's origin coordinates.
	`wrapHeight`	`wrapHeight` works similar to `wrapWidth` except that it applies to the height occupied by the text. Ellipses are appended to the end of text when text overflows beyond allocated vertical space of `wrapHeight` or `toY` attributes.
	`wrap`	Setting `"wrap": "0"` will cause text wrapping to be turned off irrespective of wrapping dimension being provided.