ChartDirector 5.1 (PHP Edition)

PieChart.setLabelLayout


Usage

setLabelLayout(layoutMethod [, pos [, topBound [, bottomBound ]]])

Description

Sets the layout method and location of the sector labels.

This method affects all sectors. To set the sector label layout method and location for one particular sector only, use Sector.setLabelLayout.

ChartDirector supports two sector label layout methods - circular layout and side layout. The layout method is determined using the layoutMethod argument, which must be one of the following predefined constants.

ConstantValueDescription
SideLayout0Side Label Layout
CircleLayout1Circular Label Layout

In the circular layout method, the sector labels are positioned around the perimeter of the pie.

In the side layout method, there is an invisible rectangle containing the pie, where the rectangle can be wider than the diameter of the pie.The sector labels are positioned on the left and right sides outside the rectangle. Because the labels can be quite far away from the sectors, join lines are typically used to connect the labels to the sectors.

The circular layout method usually uses less space and is the default layout method. However, if the pie chart contains a lot of small sectors, the labels may overlap with each others, due to insufficient space on the pie perimeter to position the labels.

The side layout method has the advantages that it can avoid label overlapping. In the side layout method, labels will automatically shift up and down to avoid overlapping.

One common issue in pie charts is the data contain a lot of small sectors. If the data are sorted, the small sectors will be crowded together instead of distributed evenly. Although the side layout method can avoid label overlapping by shifting the labels up and down, some labels may need to be shifted great distances.

Label layout can often be improved if the small sectors are near the horizontal axis. It is because the amount of vertical label space for a sector is greatest at the horizontal axis. This can be achieved by choosing an appropriate start angle (using PieChart.setStartAngle).

If the data is in ascending order (small sectors crowded at the beginning), a start angle of 45 degrees with clockwise sector layout is recommended. With this setting, the first few sectors (the smallest sectors) will be at around 45 - 135 degrees, so is near the horizontal axis (90 degrees). Similarly, if the data is in descending order (small sectors crowded at the end), a start angle of 135 degrees with clockwise sector layout can be used.

Arguments

ArgumentDefaultDescription
layoutMethod(Mandatory)Specify the layout method. Must be one of the predefined constants CircleLayout or SideLayout.
pos-1For circular layout, it is the distance between the sector perimeter and the sector label. A negative value (but not -1) means the sector label will be drawn in the interior of the sector.

For side layout, it is the distance between the pie perimeter and the left or right edges of the invisible containing rectangle (equal to the width of the rectangle minus the pie diameter and then divided by 2).

In either case, -1 means the distance is automatically determined.
topBound-1This parameter applies only to side label layout. It controls the top bound of the labels (the minimum y coordinate), thereby limiting the extent that the labels can be shifted up to avoid overlapping. This parameter is typically used avoid the labels from moving up too much and overlap with other chart objects (such as the chart title).
bottomBound-1This parameter applies only to side label layout. It controls the bottom bound of the labels (the maximum y coordinate), thereby limiting the extent which the labels can be shifted down to avoid overlapping. This parameter is typically used to avoid the labels from moving down too much and overlap with other chart objects.

Return Value

None