Source code for highcharts_core.options.accessibility.point

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 AccessibilityPoint(HighchartsMeta): """Options for describing individual points.""" def __init__(self, **kwargs): self._date_format = None self._date_formatter = None self._describe_null = None self._description_formatter = None self._value_decimals = None self._value_description_format = None self._value_prefix = None self._value_suffix = None self.date_format = kwargs.get('date_format', None) self.date_formatter = kwargs.get('date_formatter', None) self.describe_null = kwargs.get('describe_null', None) self.description_formatter = kwargs.get('description_formatter', None) self.value_decimals = kwargs.get('value_decimals', None) self.value_description_format = kwargs.get('value_description_format', None) self.value_prefix = kwargs.get('value_prefix', None) self.value_suffix = kwargs.get('value_suffix', None) @property def date_format(self) -> Optional[str]: """Date format to use for points on datetime axes when describing them to screen reader users. Defaults to the same format as in tooltip. .. seealso:: * Detailed documentation on supported format replacement codes: https://api.highcharts.com/class-reference/Highcharts.Time#dateFormat :returns: The date format to use for points on datetime axes when describing them to screen reader users. :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._date_format @date_format.setter def date_format(self, value): self._date_format = validators.string(value, allow_empty = True) @property def date_formatter(self) -> Optional[CallbackFunction]: """JavaScript formatter function to determine the date/time format used with points on datetime axes when describing them to screen reader users. The formatter function should receive one argument, ``point``, referring to the point to describe. Should return a date format string compatible with :meth:`AccessibilityPoint.date_format`. :returns: Formatter function to determine date/time format used. :rtype: :class:`CallbackFunction` or :obj:`None <python:None>` """ return self._date_formatter @date_formatter.setter @class_sensitive(CallbackFunction) def date_formatter(self, value): self._date_formatter = value @property def describe_null(self) -> Optional[bool]: """If ``True``, will describe points with the value ``null`` to assistive technology (e.g. screen readers). Defaults to ``True``. :returns: Flag indicating whether to describe points with the value ``null`` to assistive technology. :rtype: :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._describe_null @describe_null.setter def describe_null(self, value): if value is None: self._describe_null = None else: self._describe_null = bool(value) @property def description_formatter(self) -> Optional[CallbackFunction]: """JavaScript formatter function to use instead of the default for point descriptions. The JavaScript formatter function should receive one argument, ``point``, referring to the point to describe. Should return a string with the description of the point for a screen reader user. If ``false`` is returned, the default formatter will be used for that point. .. tip:: Best practice is to use :meth:`Accessibility.value_description_format` instead if possible, as default functionality such as describing annotations will be preserved. :returns: The JavaScript formatter function to use for point descriptions. :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 value_decimals(self) -> Optional[int]: """Number of digits after the decimal point to use for the values in the point description. Uses :meth:`Tooltip.value_decimals` if not provided here. :returns: Number of digits to use after the decimal point. :rtype: :class:`int <python:int>` or :obj:`None <python:None>` :raises ValueError: if a negative number is provided """ return self._value_decimals @value_decimals.setter def value_decimals(self, value): self._value_decimals = validators.integer(value, allow_empty = True, coerce_value = True, minimum = 0) @property def value_description_format(self) -> Optional[str]: """Format to use for describing the values of data points to assistive technology - including screen readers. The point context is available as ``{{point}}``. Defaults to ``{xDescription}{separator}{value}`` Other available context variables include ``{{index}}``, ``{{value}}``, and ``{{xDescription}}``. .. note:: Additionally, the series name, annotation info, and description added in :meth:`Point.accessibility.description` is added by default if relevant. To override this, use the :meth:`AccessibilityPoint.description_formatter` option. :returns: Format to use for describing the values of data points to assistive technology. :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._value_description_format @value_description_format.setter def value_description_format(self, value): self._value_description_format = validators.string(value, allow_empty = True) @property def value_prefix(self) -> Optional[str]: """Prefix to add to the values in the point descriptions. .. note:: Uses :meth:`Tooltip.value_prefix` if not defined. :returns: Prefix to add to the values in the point description. :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._value_prefix @value_prefix.setter def value_prefix(self, value): self._value_prefix = validators.string(value, allow_empty = True) @property def value_suffix(self) -> Optional[str]: """Suffix to add to the values in the point descriptions. .. note:: Uses :meth:`Tooltip.value_suffix` if not defined. :returns: Suffix to add to the values in the point description. :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._value_suffix @value_suffix.setter def value_suffix(self, value): self._value_suffix = validators.string(value, allow_empty = True) @classmethod def _get_kwargs_from_dict(cls, as_dict): kwargs = { 'date_format': as_dict.get('dateFormat', None), 'date_formatter': as_dict.get('dateFormatter', None), 'describe_null': as_dict.get('describeNull', None), 'description_formatter': as_dict.get('descriptionFormatter', None), 'value_decimals': as_dict.get('valueDecimals', None), 'value_description_format': as_dict.get('valueDescriptionFormat', None), 'value_prefix': as_dict.get('valuePrefix', None), 'value_suffix': as_dict.get('valueSuffix', None) } return kwargs def _to_untrimmed_dict(self, in_cls = None) -> dict: untrimmed = { 'dateFormat': self.date_format, 'dateFormatter': self.date_formatter, 'describeNull': self.describe_null, 'descriptionFormatter': self.description_formatter, 'valueDecimals': self.value_decimals, 'valueDescriptionFormat': self.value_description_format, 'valuePrefix': self.value_prefix, 'valueSuffix': self.value_suffix } return untrimmed