Extra Labels

Overview
Settings
Samples

Overview

Extra labels behave themselves just like ordinary labels but the have one property that is worth mentioning: they are not bound to any element. So you can place them in any place of you gauge to store some additional information. This can be extra gauge label, some brief annotation to element or whatever else you want.

Extra labels structure

Extra labels have the following structure:

XML Syntax

XML Code

    
            01
            <labels>
        
            02
              <label>
        
            03
                <position placement_mode="" halign="" valign="" padding="" x="" y="" width="" height="" spread="" />
        
            04
                <background />
        
            05
                <font />
        
            06
                <format />
        
            07
              </label>
        
            08
            </labels>

The following attributes can be set for extra labels position node:

<position>
Attribute	Values	Default	Description
placement_mode	ByPoint \| ByRectangle	Center	Defines the label placement method.
halign	Left \| Center \| Right	Center	Sets horizontal label align.
valign	Top \| Center \| Bottom	Center	Sets vertical label align.
padding	Number		Sets the padding for extra labels in percents.
x	Number		Sets the "x" coordinate of your label in percents from the width of the container.
y	Number		Sets the "y" coordinate of your label in percents from the height of the container.
width	Number	Auto	Sets the width of your label in percents from the width of the container.
height	Number	Auto	Sets the height of your label in percents from the height of the container.
spread	Boolean	False	Sets whether label background is spread to the label container.

Now let's explain the meaning of some attributes. The general difference in label placement is set by placement_mode attribute. When it has "ByPoint" value there is a anchor point for each label and all of the position changes are applied to this point. When it is set to "ByRectangle" the changes are applied to the rectangle that holds label and label's position is defined by top left point of the rectangle which in that case is anchor point.

When placement_mode is "ByPoint" halign and align choose the horizontal and vertical position of the label relative to the anchor point. When placement_mode is "ByRectangle" these attributes change the layout of the label relative to its background. x, y, width and height set the accurate position of label.

spread stretches label background for the pre-set width and height in "ByRectangle" placement_mode

Each label node also has background, font and format subnodes.

Extra labels examples

Let's create a simple example with labels positioned ByPoint and ByRectangle. Let's at first create a label that is aligned ByPoint. It will be placed under our sample gauge and will have no position attributes besides x, y and placement_mode. So, XML for this label will look like this:

XML Syntax

XML Code

    
            01
            <label>
        
            02
              <position placement_mode="ByPoint" x="85" y="90" />
        
            03
              <font size="15" />
        
            04
              <format><![CDATA["ByPoint"]]></format>
        
            05
              <background enabled="false" />
        
            06
            </label>

And the second point is similar to the first one but in another corner:

XML Syntax

XML Code

    
            01
            <label>
        
            02
              <position placement_mode="Range Bar" x="15" y="90" />
        
            03
              <font size="15" />
        
            04
              <format><![CDATA["ByPoint"]]></format>
        
            05
              <background enabled="false" />
        
            06
            </label>

And here is the result:

Live Sample: Circular Extra labels positioning sample 1

Now we create a point with these settings:

XML Syntax

XML Code

    
            01
            <label>
        
            02
              <position placement_mode="ByRectangle" x="5" y="75" spread="false" height="15" width="100" valign="Top" halign="Left" />
        
            03
              <format><![CDATA[by AnyChart]]></format>
        
            04
              <background enabled="True" />
        
            05
            </label>

And the second label. We make it bigger than others, but due to "True" value of align attribute and "Bottom" and "Right" values for valign and halign respectively the text of the label will be located in the lower right corner relative to label's background.

XML Syntax

XML Code

    
            01
            <label>
        
            02
              <position placement_mode="ByRectangle" x="55" y="72" spread="true" height="25" width="40" valign="Bottom" halign="Right" />
        
            03
              <format><![CDATA[Right-Bottom]]></format>
        
            04
              <background enabled="True" />
        
            05
            </label>

Here are all 2 labels:

Live Sample: Circular Extra labels positioning sample 2

Note that although the width for the first label ("by AnyChart") is set to 100, its background doesn't stretch to all the width of the container. That's because of "False" value of spread attribute.