Source code for bokeh.models.widgets.sliders

#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2022, Anaconda, Inc., and Bokeh Contributors.
# All rights reserved.
#
# The full license is in the file LICENSE.txt, distributed with this software.
#-----------------------------------------------------------------------------
''' Various kinds of slider widgets.

'''

#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
from __future__ import annotations

import logging # isort:skip
log = logging.getLogger(__name__)

#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------

# Standard library imports
import numbers
from datetime import date, datetime

# Bokeh imports
from ...core.has_props import abstract
from ...core.properties import (
    Bool,
    Color,
    Datetime,
    Either,
    Enum,
    Float,
    Instance,
    Int,
    Nullable,
    Override,
    Readonly,
    Required,
    String,
    Tuple,
)
from ...core.validation import error
from ...core.validation.errors import EQUAL_SLIDER_START_END
from ..formatters import TickFormatter
from .widget import Widget

#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------

__all__ = (
    'AbstractSlider',
    'Slider',
    'RangeSlider',
    'DateSlider',
    'DateRangeSlider',
    'DatetimeRangeSlider',
)

#-----------------------------------------------------------------------------
# Dev API
#-----------------------------------------------------------------------------

[docs]@abstract class AbstractSlider(Widget): """ """ def __init__(self, *args, **kwargs) -> None: if 'start' in kwargs and 'end' in kwargs: if kwargs['start'] == kwargs['end']: raise ValueError("Slider 'start' and 'end' cannot be equal.") if "value" in kwargs and "value_throttled" not in kwargs: kwargs["value_throttled"] = kwargs["value"] super().__init__(*args, **kwargs) orientation = Enum("horizontal", "vertical", help=""" Orient the slider either horizontally (default) or vertically. """) title = Nullable(String, default="", help=""" The slider's label (supports :ref:`math text <ug_styling_mathtext>`). """) show_value = Bool(default=True, help=""" Whether or not show slider's value. """) format = Either(String, Instance(TickFormatter), help=""" """) direction = Enum("ltr", "rtl", help=""" """) tooltips = Bool(default=True, help=""" Display the slider's current value in a tooltip. """) bar_color = Color(default="#e6e6e6", help=""" """) width = Override(default=300) @error(EQUAL_SLIDER_START_END) def _check_missing_dimension(self): if hasattr(self, 'start') and hasattr(self, 'end'): if self.start == self.end: return f"{self!s} with title {self.title!s}"
#----------------------------------------------------------------------------- # General API #-----------------------------------------------------------------------------
[docs]class Slider(AbstractSlider): """ Slider-based number selection widget. """ # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) start = Required(Float, help=""" The minimum allowable value. """) end = Required(Float, help=""" The maximum allowable value. """) value = Required(Float, help=""" Initial or selected value. """) value_throttled = Readonly(Required(Float), help=""" Initial or selected value, throttled according to report only on mouseup. """) step = Float(default=1, help=""" The step between consecutive values. """) format = Override(default="0[.]00")
[docs]class RangeSlider(AbstractSlider): """ Range-slider based number range selection widget. """ # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) value = Required(Tuple(Float, Float), help=""" Initial or selected range. """) value_throttled = Readonly(Required(Tuple(Float, Float)), help=""" Initial or selected value, throttled according to report only on mouseup. """) start = Required(Float, help=""" The minimum allowable value. """) end = Required(Float, help=""" The maximum allowable value. """) step = Float(default=1, help=""" The step between consecutive values. """) format = Override(default="0[.]00")
[docs]class DateSlider(AbstractSlider): """ Slider-based date selection widget. """ # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) @property def value_as_datetime(self) -> datetime | None: ''' Convenience property to retrieve the value as a datetime object. Added in version 2.0 ''' if self.value is None: return None if isinstance(self.value, numbers.Number): return datetime.utcfromtimestamp(self.value / 1000) return self.value @property def value_as_date(self) -> date | None: ''' Convenience property to retrieve the value as a date object. Added in version 2.0 ''' if self.value is None: return None if isinstance(self.value, numbers.Number): dt = datetime.utcfromtimestamp(self.value / 1000) return date(*dt.timetuple()[:3]) return self.value value = Required(Datetime, help=""" Initial or selected value. """) value_throttled = Readonly(Required(Datetime), help=""" Initial or selected value, throttled to report only on mouseup. """) start = Required(Datetime, help=""" The minimum allowable value. """) end = Required(Datetime, help=""" The maximum allowable value. """) step = Int(default=1, help=""" The step between consecutive values, in units of days. """) format = Override(default="%d %b %Y")
[docs]class DateRangeSlider(AbstractSlider): """ Slider-based date range selection widget. """ # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) @property def value_as_datetime(self) -> tuple[datetime, datetime] | None: ''' Convenience property to retrieve the value tuple as a tuple of datetime objects. Added in version 1.1 ''' if self.value is None: return None v1, v2 = self.value if isinstance(v1, numbers.Number): d1 = datetime.utcfromtimestamp(v1 / 1000) else: d1 = v1 if isinstance(v2, numbers.Number): d2 = datetime.utcfromtimestamp(v2 / 1000) else: d2 = v2 return d1, d2 @property def value_as_date(self) -> tuple[date, date] | None: ''' Convenience property to retrieve the value tuple as a tuple of date objects. Added in version 1.1 ''' if self.value is None: return None v1, v2 = self.value if isinstance(v1, numbers.Number): dt = datetime.utcfromtimestamp(v1 / 1000) d1 = date(*dt.timetuple()[:3]) else: d1 = v1 if isinstance(v2, numbers.Number): dt = datetime.utcfromtimestamp(v2 / 1000) d2 = date(*dt.timetuple()[:3]) else: d2 = v2 return d1, d2 value = Required(Tuple(Datetime, Datetime), help=""" Initial or selected range. """) value_throttled = Readonly(Required(Tuple(Datetime, Datetime)), help=""" Initial or selected value, throttled to report only on mouseup. """) start = Required(Datetime, help=""" The minimum allowable value. """) end = Required(Datetime, help=""" The maximum allowable value. """) step = Int(default=1, help=""" The step between consecutive values, in units of days. """) format = Override(default="%d %b %Y")
[docs]class DatetimeRangeSlider(AbstractSlider): """ Slider-based datetime range selection widget. """ # explicit __init__ to support Init signatures def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) @property def value_as_datetime(self) -> tuple[datetime, datetime] | None: ''' Convenience property to retrieve the value tuple as a tuple of datetime objects. ''' if self.value is None: return None v1, v2 = self.value if isinstance(v1, numbers.Number): d1 = datetime.utcfromtimestamp(v1 / 1000) else: d1 = v1 if isinstance(v2, numbers.Number): d2 = datetime.utcfromtimestamp(v2 / 1000) else: d2 = v2 return d1, d2 value = Required(Tuple(Datetime, Datetime), help=""" Initial or selected range. """) value_throttled = Readonly(Required(Tuple(Datetime, Datetime)), help=""" Initial or selected value, throttled to report only on mouseup. """) start = Required(Datetime, help=""" The minimum allowable value. """) end = Required(Datetime, help=""" The maximum allowable value. """) step = Int(default=3_600_000, help=""" The step between consecutive values, in units of milliseconds. Default is one hour. """) format = Override(default="%d %b %Y %H:%M:%S")
#----------------------------------------------------------------------------- # Private API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Code #-----------------------------------------------------------------------------