ChartDataLabel class

ChartDataLabel class

Represents data label on a chart point or trendline. To learn more, visit the Working with Charts documentation article.

Remarks

On a series, the ChartDataLabel object is a member of the ChartDataLabelCollection. The ChartDataLabelCollection contains a ChartDataLabel object for each point.

Properties

NameDescription
fontProvides access to the font formatting of this data label.
formatProvides access to fill and line formatting of the data label.
indexSpecifies the index of the containing element. This index shall determine which of the parent’s children collection this element applies to. Default value is 0.
is_hiddenGets/sets a flag indicating whether this label is hidden. The default value is False.
is_visibleReturns True if this data label has something to display.
number_formatReturns number format of the parent element.
orientationGets or sets the orientation of the label text.
rotationGets or sets the rotation of the label in degrees.
separatorGets or sets string separator used for the data labels on a chart. The default is a comma, except for pie charts showing only category name and percentage, when a line break shall be used instead.
show_bubble_sizeAllows to specify if bubble size is to be displayed for the data labels on a chart. Applies only to Bubble charts. Default value is False.
show_category_nameAllows to specify if category name is to be displayed for the data labels on a chart. Default value is False.
show_data_labels_rangeAllows to specify if values from data labels range to be displayed in the data labels. Default value is False.
show_leader_linesAllows to specify if data label leader lines need be shown. Default value is False.
show_legend_keyAllows to specify if legend key is to be displayed for the data labels on a chart. Default value is False.
show_percentageAllows to specify if percentage value is to be displayed for the data labels on a chart. Default value is False.
show_series_nameReturns or sets a Boolean to indicate the series name display behavior for the data labels on a chart. True to show the series name; False to hide. By default False.
show_valueAllows to specify if values are to be displayed in the data labels. Default value is False.

Methods

NameDescription
clear_format()Clears format of this data label. The properties are set to the default values defined in the parent data label collection.

Examples

Shows how to apply labels to data points in a line chart.

def data_labels():
    doc = aw.Document()
    builder = aw.DocumentBuilder(doc)
    chart_shape = builder.insert_chart(aw.drawing.charts.ChartType.LINE, 400, 300)
    chart = chart_shape.chart
    self.assertEqual(3, chart.series.count)
    self.assertEqual('Series 1', chart.series[0].name)
    self.assertEqual('Series 2', chart.series[1].name)
    self.assertEqual('Series 3', chart.series[2].name)
    # Apply data labels to every series in the chart.
    # These labels will appear next to each data point in the graph and display its value.
    for series in chart.series:
        apply_data_labels(series, 4, '000.0', ', ')
        self.assertEqual(4, series.data_labels.count)
    # Change the separator string for every data label in a series.
    for label in chart.series[0].data_labels:
        self.assertEqual(', ', label.separator)
        label.separator = ' & '
    # For a cleaner looking graph, we can remove data labels individually.
    chart.series[1].data_labels[2].clear_format()
    # We can also strip an entire series of its data labels at once.
    chart.series[2].data_labels.clear_format()
    doc.save(ARTIFACTS_DIR + 'Charts.data_labels.docx')

def apply_data_labels(series: aw.drawing.charts.ChartSeries, labels_count: int, number_format: str, separator: str):
    """Apply data labels with custom number format and separator to several data points in a series."""
    for i in range(labels_count):
        series.has_data_labels = True
        self.assertFalse(series.data_labels[i].is_visible)
        series.data_labels[i].show_category_name = True
        series.data_labels[i].show_series_name = True
        series.data_labels[i].show_value = True
        series.data_labels[i].show_leader_lines = True
        series.data_labels[i].show_legend_key = True
        series.data_labels[i].show_percentage = False
        series.data_labels[i].is_hidden = False
        self.assertFalse(series.data_labels[i].show_data_labels_range)
        series.data_labels[i].number_format.format_code = number_format
        series.data_labels[i].separator = separator
        self.assertFalse(series.data_labels[i].show_data_labels_range)
        self.assertTrue(series.data_labels[i].is_visible)
        self.assertFalse(series.data_labels[i].is_hidden)

See Also