Source code for highcharts_core.options.accessibility.series

from typing import Optional

from validator_collection import validators

from highcharts_core import constants
from highcharts_core.decorators import class_sensitive
from highcharts_core.metaclasses import HighchartsMeta
from highcharts_core.utility_classes.javascript_functions import CallbackFunction

[docs]class SeriesAccessibility(HighchartsMeta): """Accessibility options global to all data series. .. hint:: Individual series can also have specific accessibility options set. """ def __init__(self, **kwargs): self._describe_single_series = None self._description_format = None self._description_formatter = None self._point_description_enabled_threshold = None self.describe_single_series = kwargs.get('describe_single_series', None) self.description_format = kwargs.get('description_format', None) self.description_formatter = kwargs.get('description_formatter', None) self.point_description_enabled_threshold = kwargs.get( 'point_description_enabled_threshold', None ) @property def describe_single_series(self) -> Optional[bool]: """If ``True``, will add series descriptions to charts with a single series. Defaults to ``False``. :returns: Flag indicating whether to add series descriptions to charts with a single series. :rtype: :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._describe_single_series @describe_single_series.setter def describe_single_series(self, value): if value is None: self._describe_single_series = None else: self._describe_single_series = bool(value) @property def description_format(self) -> Optional[str]: """Format to use for describing the data series group to assistive technology - including screen readers. Defaults to ``'{seriesDescription}{authorDescription}{axisDescription}'``. The series context and its subproperties are available under the variable ``{{series}}``, for example ``{{}}`` for the series name, and ``{{series.points.length}}`` for the number of data points. The chart context and its subproperties are available under the variable ``{{chart}}``, for example ``{{chart.series.length}}`` for the number of series in the chart. ``{{seriesDescription}}`` refers to the automatic description of the series type and number of points added by Highcharts by default. ``{{authorDescription}}`` refers to the description added in ``series.description`` if one is present. ``{{axisDescription}}`` refers to the description added if the chart has multiple X or Y axes. Note that if :meth:`Series.description_formatter` is not :obj:`None <python:None>` it will take precedence, and this option will be overridden. :returns: Format string that applies to the description produced for the data series. :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._description_format @description_format.setter def description_format(self, value): self._description_format = validators.string(value, allow_empty = True) @property def description_formatter(self) -> Optional[CallbackFunction]: """JavaScript formatter function to use instead of the default for series descriptions. Should receives one argument, series, referring to the series to describe. Should return a string with the description of the series for a screen reader user. If ``false`` is returned, the default formatter will be used for that series. :returns: JavaScript formatter function :rtype: :class:`CallbackFunction` or :obj:`None <python:None>` """ return self._description_formatter @description_formatter.setter @class_sensitive(CallbackFunction) def description_formatter(self, value): self._description_formatter = value @property def point_description_enabled_threshold(self) -> Optional[bool | int]: """When a series contains more points than the value set for this property, Highcharts will no longer expose information about individual points to screen readers. Defaults to ``200``. .. hint:: If set to ``False``, the threshold will be disabled and all points will be described. :returns: The threshold for number of data points above which point description information wlil not be provided. :rtype: :class:`int <python:int>` or :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._point_description_enabled_threshold @point_description_enabled_threshold.setter def point_description_enabled_threshold(self, value): if value is None: self._point_description_enabled_threshold = None elif isinstance(value, bool) and value is False: self._point_description_enabled_threshold = False else: self._point_description_enabled_threshold = validators.integer( value, allow_empty = False, coerce_value = True, minimum = 1 ) @classmethod def _get_kwargs_from_dict(cls, as_dict): kwargs = { 'describe_single_series': as_dict.get('describeSingleSeries', None), 'description_format': as_dict.get('descriptionFormat', None), 'description_formatter': as_dict.get('descriptionFormatter', None), 'point_description_enabled_threshold': as_dict.get( 'pointDescriptionEnabledThreshold', None ), } return kwargs def _to_untrimmed_dict(self, in_cls = None) -> dict: untrimmed = { 'describeSingleSeries': self.describe_single_series, 'descriptionFormat': self.description_format, 'descriptionFormatter': self.description_formatter, 'pointDescriptionEnabledThreshold': self.point_description_enabled_threshold } return untrimmed