Source code for highcharts_core.options.caption

from typing import Optional
from decimal import Decimal

from validator_collection import validators

from highcharts_core import constants, errors
from highcharts_core.metaclasses import HighchartsMeta


[docs]class Caption(HighchartsMeta): """The chart's caption, which will render below the chart and will be part of exported charts. .. note:: The caption can be updated after chart initialization in JavaScript through the ``Chart.update()`` or ``Chart.caption.update()`` methods. """ def __init__(self, **kwargs): self._align = None self._floating = None self._margin = None self._style = None self._text = None self._use_html = None self._vertical_align = None self._x = None self._y = None self.align = kwargs.get('align', None) self.floating = kwargs.get('floating', None) self.margin = kwargs.get('margin', None) self.style = kwargs.get('style', None) self.text = kwargs.get('text', None) self.use_html = kwargs.get('use_html', None) self.vertical_align = kwargs.get('vertical_align', None) self.x = kwargs.get('x', None) self.y = kwargs.get('y', None) @property def align(self) -> Optional[str]: """The alignment of the caption. Defaults to ``'left'``. Accepts: * ``'left'`` * ``'center'`` * ``'right'`` :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._align @align.setter def align(self, value): if not value: self._align = None else: value = validators.string(value, allow_empty = False) value = value.lower() if value not in ['left', 'center', 'right']: raise errors.HighchartsValueError(f'align must be either "left", ' f'"center", or "right". Was: {value}') self._align = value @property def floating(self) -> Optional[bool]: """If ``True`, sets the caption to floating. When the caption is floating, the plot area will not move to make space for it. Defaults to ``False``. :rtype: :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._floating @floating.setter def floating(self, value): if value is None: self._floating = None else: self._floating = bool(value) @property def margin(self) -> Optional[int | float | Decimal]: """The margin between the caption and the plot area. Defaults to ``15``. :rtype: numeric or :obj:`None <python:None>` """ return self._margin @margin.setter def margin(self, value): self._margin = validators.numeric(value, allow_empty = True) @property def style(self) -> Optional[str]: """CSS styling to apply to the caption. Defaults to ``'{"color": "#666666"}'``. :rtype: :class:`str` or :obj:`None <python:None>` """ return self._style @style.setter def style(self, value): self._style = validators.string(value, allow_empty = True, coerce_value = True) @property def text(self) -> Optional[str]: """The caption text of the chart. Defaults to an empty string (``''``). :rtype: :class:`str <python:str>` """ return self._text or '' @text.setter def text(self, value): self._text = validators.string(value, allow_empty = True) @property def use_html(self) -> Optional[bool]: """If ``True``, will use HTML to render the caption. If ``False``, will use SVG or WebGL as applicable. Defaults to ``False``. :returns: Flag indicating whether to render the caption using HTML. :rtype: :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._use_html @use_html.setter def use_html(self, value): if value is None: self._use_html = None else: self._use_html = bool(value) @property def vertical_align(self) -> Optional[str]: """The vertical alignment of the caption. Defaults to ``'bottom'``. Accepts: * ``'bottom'`` * ``'middle'`` * ``'top'`` :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._vertical_align @vertical_align.setter def vertical_align(self, value): value = validators.string(value, allow_empty = True) if not value: self._vertical_align = None else: value = value.lower() if value not in ['bottom', 'middle', 'top']: raise errors.HighchartsValueError(f'vertical_align expects either "top", ' f'"middle", or "bottom". Was: {value}') self._vertical_align = value @property def x(self) -> Optional[int | float | Decimal]: """The x position of the caption relative to the alignment within :meth:`Options.chart.spacing_left` and :meth:`Option.chart.spacing_right`. Defaults to ``0``. :rtype: numeric or :obj:`None <python:None>` """ return self._x @x.setter def x(self, value): self._x = validators.numeric(value, allow_empty = True) @property def y(self) -> Optional[int]: """The y position of the caption relative to the alignment within :meth:`Options.chart.spacing_left` and :meth:`Option.chart.spacing_right`. Defaults to ``None``. :rtype: numeric or :obj:`None <python:None>` """ return self._y @y.setter def y(self, value): self._y = validators.numeric(value, allow_empty = True) @classmethod def _get_kwargs_from_dict(cls, as_dict): kwargs = { 'align': as_dict.get('align', None), 'floating': as_dict.get('floating', None), 'margin': as_dict.get('margin', None), 'style': as_dict.get('style', None), 'text': as_dict.get('text', None), 'use_html': as_dict.get('useHTML', None), 'vertical_align': as_dict.get('verticalAlign', None), 'x': as_dict.get('x', None), 'y': as_dict.get('y', None), } return kwargs def _to_untrimmed_dict(self, in_cls = None) -> dict: untrimmed = { 'align': self.align, 'floating': self.floating, 'margin': self.margin, 'style': self.style, 'text': self.text, 'useHTML': self.use_html, 'verticalAlign': self.vertical_align, 'x': self.x, 'y': self.y } return untrimmed