Chart - Data Labels

On a PowerPoint chart, data points may be labeled as an aid to readers. Typically, the label is the value of the data point, but a data label may have any combination of its series name, category name, and value. A number format may also be applied to the value displayed.

Object access

The DataLabels object is not a collection of DataLabel objects. DataLabels controls the formatting of the data labels for a whole series, so “global” settings in a way of thinking. An individual DataLabel object is accessed using it’s associated Point object:

data_label = chart.plot[0].series[0].points[0].data_label

The two object types share many attributes.

DataLabel.font

Proposed protocol:

>>> font = data_label.font
>>> font.color.rgb = RGBColor(0x3C, 0xEB, 0x27)

Position

There are nine choices for where a data label may be positioned relative to its data point marker, although the available options depend on the chart type. The options are specified using the XL_DATA_LABEL_POSITION enumeration.

XML Semantics. The default position when no <c:dLblPos> element is present (common) depends on the chart type:

barChart (clustered) OUTSIDE_END
bar3DChart (clustered) OUTSIDE_END
barChart (stacked) CENTER
barChart (percent stacked) CENTER
bar3DChart (stacked) CENTER
bar3DChart (percent stacked) CENTER
pieChart BEST_FIT
pie3DChart BEST_FIT
ofPieChart BEST_FIT
areaChart CENTER
area3DChart CENTER
doughnutChart CENTER
radarChart OUTSIDE_END
all others RIGHT

http://msdn.microsoft.com/en-us/library/ff535061(v=office.12).aspx

Proposed protocol:

>>> data_labels = plot.data_labels
>>> data_labels.position
OUTSIDE_END (2)
>>> data_labels.position = XL_DATA_LABEL_POSITION.INSIDE_END
>>> data_labels.position
INSIDE_END (3)

MS API

The following properties from the MS API DataLabel object are of most interest:

Delete()
Deletes the DataLabel object, which might be useful for “undoing” data label overrides and restoring inherited behaviors.
AutoText
True if the object automatically generates appropriate text based on context. Read/write Boolean.
Caption
Returns or sets the data label text. Read/write String.
Format
Returns the line, fill, and effect formatting for the object. Read-only ChartFormat.
NumberFormat
Returns or sets the format code for the object. Read/write String.
NumberFormatLinked
True if the number format is linked to the cells (so that the number format changes in the labels when it changes in the cells). Read/write Boolean.
Orientation
Returns or sets the text orientation. Read/write Long in range -90 to 90 (degrees).
Position
Returns or sets the position of the data label. Read/write XlDataLabelPosition.
Separator
Returns or sets the separator used for the data labels on a chart. Used when more than one value is shown, like category+value. Read/write Variant.
Shadow
Returns or sets a value that indicates whether the object has a shadow. Read/write Boolean.
ShowBubbleSize
True to show the bubble size for the data labels on a chart. False to hide the bubble size. Read/write Boolean.
ShowCategoryName
True to display the category name for the data labels on a chart. False to hide the category name. Read/write Boolean.
ShowLegendKey
True if the data label legend key is visible. This is a small square of the series color shown in the legend, and appears adjacent to the data label. Read/write Boolean.
ShowPercentage
True to display the percentage value for the data labels on a chart. False to hide the value. This might only be relevant for pie charts and similar. Read/write Boolean.
ShowSeriesName
True to show the series name for the data labels on a chart. False to hide the series name. Read/write Boolean.
ShowValue
True to display a specified chart’s data label values. False to hide the values. Read/write Boolean.
Text
Returns or sets the text for the specified object. Read/write String.
VerticalAlignment
Returns or sets the vertical alignment of the specified object. Read/write Variant.

PowerPoint behavior

  • A default PowerPoint bar chart does not display data labels, but it does have a <c:dLbls> child element on its <c:barChart> element.
  • Data labels are added to a chart in the UI by selecting the Data Labels drop-down menu in the Chart Layout ribbon. The options include setting the contents of the data label, its position relative to the point, and bringing up the Format Data Labels dialog.
  • The default number format, when no <c:numFmt> child element appears, is equivalent to <c:numFmt formatCode="General" sourceLinked="1"/>

XML Semantics

  • A <c:dLbls> element at the plot level (e.g. <c:barChart>) is overridden completely by a <c:dLbls> element at the series level. Unless overridden, a <c:dLbls> element at the plot level determines the content and formatting for data labels on all the plot’s series.
  • A <c:dLbl> element appears as a child of <c:dLbls> only when the data label for its associated data point has overrides.

XML specimens

The <c:dLbls> element is available on a plot (e.g. <c:barChart>), a series (<c:ser>), and perhaps elsewhere.

Default <c:dLbls> element added by PowerPoint when selecting Data Labels > Value from the Chart Layout ribbon:

<c:dLbls>
  <c:showLegendKey val="0"/>
  <c:showVal val="1"/>
  <c:showCatName val="0"/>
  <c:showSerName val="0"/>
  <c:showPercent val="0"/>
  <c:showBubbleSize val="0"/>
</c:dLbls>

A <c:dLbls> element specifying the labels should appear in 10pt Bold Italic Arial Narrow, color Accent 6, 25% Darker:

<c:dLbls>
  <c:txPr>
    <a:bodyPr/>
    <a:lstStyle/>
    <a:p>
      <a:pPr>
        <a:defRPr sz="1000" b="1" i="1">
          <a:solidFill>
            <a:schemeClr val="accent6">
              <a:lumMod val="75000"/>
            </a:schemeClr>
          </a:solidFill>
          <a:latin typeface="Arial Narrow"/>
        </a:defRPr>
      </a:pPr>
      <a:endParaRPr lang="en-US"/>
    </a:p>
  </c:txPr>
  <c:showLegendKey val="0"/>
  <c:showVal val="1"/>
  <c:showCatName val="0"/>
  <c:showSerName val="0"/>
  <c:showPercent val="0"/>
  <c:showBubbleSize val="0"/>
</c:dLbls>

A <c:dLbls> element having an individual point override for font color and outline box:

<c:dLbls>
  <c:dLbl>
    <c:idx val="0"/>
    <c:spPr>
      <!-- ouline color (Red) -->
      <a:ln>
        <a:solidFill>
          <a:srgbClr val="FF0000"/>
        </a:solidFill>
      </a:ln>
    </c:spPr>
    <c:txPr>
      <a:bodyPr/>
      <a:lstStyle/>
      <a:p>
        <a:pPr>
          <!-- font color (Green) -->
          <a:defRPr>
            <a:solidFill>
              <a:srgbClr val="00FF00"/>
            </a:solidFill>
          </a:defRPr>
        </a:pPr>
        <a:endParaRPr lang="en-US"/>
      </a:p>
    </c:txPr>
    <c:showLegendKey val="0"/>
    <c:showCatName val="0"/>
    <c:showSerName val="0"/>
  </c:dLbl>
  <c:spPr/>
  <!-- ... -->
</c:dLbls>